openapi: 3.1.0
info:
  title: Konnect API reference
  description: >
    Welcome to the Fynd Konnect API Reference, 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

      > Fynd Konnect is a unified platform built to streamline 
        e-commerce and omni-channel operations by connecting seller's downstream systems (WMS, ERP, POS)
        with the the top marketplaces and webstores alongside Fynd Commerce
  version: 1.0.0
servers:
  - url: https://fyndkonnect.konnect.uat.fyndx1.de
    description: Fynd Konnect [Sandbox]
  - url: https://ginesys.konnect.uat.fyndx1.de
    description: Ginesys <> Konnect [Sandbox]
  - url: https://unicommerce.konnect.uat.fyndx1.de
    description: Unicommerce <> Konnect [Sandbox]
tags:
  - name: Authorization
    description: >
      - 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
  - name: Catalog
    description: >
      - Lets a partner maintain and retrieve detailed product listings in the
      Fynd OMS
        Includes endpoints to fetch the total SKU count and specific product listings
        with pagination or SKU filters
        
      - Ideal for validating data synchronization,
        bulk updates, or verifying new product onboarding
  - name: Pricing
    description: >
      - 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
  - name: Inventory
    description: >
      - 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
  - name: Orders
    description: >
      - 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
  - name: Returns
    description: |
      - 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
paths:
  /aggregator/v1/token:
    get:
      operationId: GenerateAccessToken
      tags:
        - Authorization
      summary: Generate Access Token
      description: >
        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.
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
          description: Company or Store-level integration username
        - name: password
          in: query
          required: true
          schema:
            type: string
          description: Company or Store-level integration token/password
      responses:
        '200':
          description: Successful authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    access_token: >-
                      eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI2NzJjODc1MzdiZWJjYzZkMWQ1MTdhZDMiLCJpYXQiOjE3MzI4NjE1OTksInJvbGUiOlsiUk9MRV9DT01QQU5ZIl0sImV4cCI6MTczMjk2MTU5OH0.6JZ-NgVn3V5duyQsrq30sODAfWY-bhMvzUxS6DYV-erfedufnb3413ewqdW341Vrwe24w1esqdsdqwe2
                    status: SUCCESS
        '400':
          description: Bad credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BadRequest:
                  summary: 400 Bad Request
                  value:
                    error: Bad credentials
                    status: FAILED
        '404':
          description: Endpoint not found
          content:
            text/plain:
              schema:
                type: string
              examples:
                NotFound:
                  summary: 404 Not Found
                  value: default backend
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ServerError:
                  summary: 500 Internal Server Error
                  value:
                    error: Internal Server Error
                    status: FAILED
  /ims/v3/listings:
    get:
      operationId: GetProductListings
      tags:
        - Catalog
      summary: Product Listings
      description: >
        Retrieve SKUs from the 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`
          - Up to 10 SKU filters in one request
      security:
        - ApiKeyAuth: []
      parameters:
        - name: page_no
          in: query
          required: false
          schema:
            type: string
          description: The current page number of the request
        - name: page_size
          in: query
          required: false
          schema:
            type: string
          description: Number of items per page (max 500)
        - name: skus
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated SKUs (max 10) to fetch certain product listings
      responses:
        '200':
          description: Successful retrieval of product listings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListing'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      - sku: '25884050999'
                        quantity: 100
                        location_id: FYND-MUM
                        esp: 999
                        mrp: 999
                      - sku: '8907583479532'
                        quantity: 100
                        location_id: FYND-MUM
                        esp: 1000
                        mrp: 1000
                      - sku: '8907583479525'
                        quantity: 55
                        location_id: FYND-MUM
                        esp: 1000
                        mrp: 1000
                    meta:
                      ack_id: 55a7bd5d-4dbd-46ed-8cc9-8677e9d691fa
                      integrationId: 63b8e31227ah5327f0affee7
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: SUCCESS
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: access denied
  /ims/v3/listings/count:
    get:
      operationId: GetProductCount
      tags:
        - Catalog
      summary: Product Count
      description: >
        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.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: x-batch-product
          in: header
          required: false
          schema:
            type: string
            enum:
              - true
              - false
          description: Flag indicating batch processing for the product count
      responses:
        '200':
          description: Successful retrieval of product count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCount'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      listing_count: 55050
                    meta:
                      ack_id: ef0f3996-d414-134a-b9e9-09658a5cb781
                      integrationId: 63b8e31227ah5327f0affee7
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: SUCCESS
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: access denied
        '504':
          description: Gateway Timeout
          content:
            text/plain:
              schema:
                type: string
              example: stream timeout
  /ims/v3/price:
    put:
      operationId: UpdatePrice
      tags:
        - Pricing
      summary: Update Price
      description: >
        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.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceUpdate'
      responses:
        '200':
          description: Successful (or partial) price update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      payload_count: 2
                      success_count: 2
                      failed_count: 0
                      errors: []
                    meta:
                      ack_id: 679c771cc8f3483beac7862d
                      integrationId: 64b8e312269b5327f0affee7
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: SUCCESS
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: access denied
  /ims/v3/inventory:
    put:
      operationId: UpdateInventory
      tags:
        - Inventory
      summary: Update Inventory
      description: >
        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.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryUpdate'
      responses:
        '200':
          description: Successful (or partial) inventory update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      payload_count: 2
                      success_count: 2
                      failed_count: 0
                      errors: []
                    meta:
                      ack_id: 679c7a1e733b526d91f9a1b8
                      integrationId: 64b8e312269b5327f0affee7
                      time: '2025-01-31T06:58:37.608+00:00'
                      status: SUCCESS
        '401':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T07:23:43.945+00:00'
                      status: access denied
  /oms/v3/shipment:
    get:
      operationId: GetOrders
      tags:
        - Orders
      summary: Fetch Orders
      description: >
        - 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. 
      security:
        - ApiKeyAuth: []
      parameters:
        - name: orderId
          in: query
          required: false
          schema:
            type: string
          description: >
            Unique shipment identifier 


            > If a particular order need to be fetched, none of the other
            parameters need to be filled; only the `orderId` is required
        - name: orderingChannel
          in: query
          required: false
          schema:
            type: string
          description: Filter shipments by the sales channel (e.g., ECOMM, FYND)
        - name: orderStatus
          in: query
          required: true
          schema:
            type: string
          description: >
            Filters orders by current status (CREATED, CONFIRMED, PROCESSING,
            etc.).  


            > To fetch Returns, use `RETURN_DELIVERED`
        - name: pageNumber
          in: query
          required: false
          schema:
            type: integer
          description: Page number for paginated results
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
          description: Number of results per page
        - name: locationCode
          in: query
          required: false
          schema:
            type: string
          description: |
            Store or warehouse location code  
            If using Company-level auth, locationCode is mandatory
        - name: orderDateFrom
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filters orders from this date (dd-mm-yyyy)
        - name: orderDateTo
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filters orders up to this date (dd-mm-yyyy)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    - id: '17328629784861446350'
                      forwardId: '17328629784861446350'
                      marketplaceOrderId: FY674964020E8E174561
                      marketplaceReturnId: null
                      marketplaceInvoiceNumber: null
                      shippingAddress:
                        addressLine1: Vijay Diamond
                        phone: '9999999999'
                        city: Mumbai
                        email: ''
                        name: John Doe
                        pincode: '400093'
                        state: Maharashtra
                        country: India
                      billingAddress:
                        addressLine1: Vijay Diamond
                        phone: '9999999999'
                        city: Mumbai
                        email: ''
                        name: John Doe
                        pincode: '400093'
                        state: Maharashtra
                        country: India
                      multiPackShipment: false
                      packages:
                        - packageId: P1
                          packageLengthCm: 43.18
                          packageWidthCm: 34.29
                          packageHeightCm: 11
                          packageWeightGms: 200
                      fulfillmentType: marketplaceFulfilled
                      sellerInvoiced: false
                      courierName: Fynd-Test
                      courierCode: Fynd-Test
                      awbNumber: []
                      additionalInfo: You can add additional info here
                      orderPrice:
                        currency: INR
                        orderTotalAmount: 999
                        codAmount: 999
                      orderItems:
                        - title: Cotton White Shirt
                          orderItemId: '3268256'
                          quantity: 1
                          gstDetails:
                            taxPercentage:
                              sgst: 3
                              cgst: 3
                            taxAmount:
                              sgst: 29.1
                              cgst: 29.1
                          imeiSerialNumberNeeded: false
                          imeiSerialNumber: []
                          locationCode: FYND-MUM
                          productIdentifiers:
                            sku_code: PRDO-27382-XL
                          onHold: false
                          orderItemPrice:
                            totalMarkedPrice: 1100
                            discount: 101
                            transferPrice: 0
                            totalItemPrice: 999
                            currency: INR
                            shippingCharges: 0
                            cashOnDeliveryCharges: 0
                            giftWrapCharges: 0
                          marketplaceOrderItemId: '3268256'
                          productId: prdo-27382
                          shippingMethodCode: STD
                          status: CONFIRMED
                          sku: prdo-27382
                          packetNumber: 0
                          variantId: XL
                      orderStatus: DELIVERED
                      orderDate: '2025-01-25T12:19:38+00:00'
                      modifiedDate: '2025-01-30T12:21:04'
                      paymentType: COD
                      taxExempted: false
                      gstin: null
                      packAfterDate: null
                      packByDate: null
                      pickUpSlots: []
                      orderingChannel: Konnect Test
                      labelPdfUrl: null
                      purchaseOrderPdfUrl: null
                      invoiceNumber: null
                      returnInvoiceNumber: null
                      irnNumber: null
                      invoiceQrCode: null
                      signedInvoice: null
                      orderBusinessType: B2C
                      lockStatus: false
                      fulfillmentPriority: null
                      journeyType: forward
                      cformProvided: false
                      A4invoicePdfUrl: null
                      A6invoicePdfUrl: >-
                        https://storage.googleapis.com/fynd-staging-assets-private/...
                      is_returnless: false
                      is_self_ship: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
  /oms/v3/shipment/cancel:
    post:
      operationId: CancelOrder
      tags:
        - Orders
      summary: Order Cancellation
      description: >-
        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.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: Unique identifier for the order to be canceled
                  orderItems:
                    type: array
                    items:
                      type: object
                      properties:
                        orderItemId:
                          type: string
                          description: Unique identifier for the specific bag item(s)
                        quantity:
                          type: integer
                          description: Quantity of this order item to be canceled
                        reasonCode:
                          type: string
                          description: >-
                            Reason code explaining why the bag item(s) is being
                            canceled
                required:
                  - orderId
      responses:
        '200':
          description: Order cancellation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                payloadCount: 2
                successCount: 2
                failedCount: 0
                status: SUCCESS
                errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/confirm:
    post:
      operationId: ConfirmOrder
      tags:
        - Orders
      summary: Order Confirmation
      description: >
        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.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: Unique identifier for the order being confirmed
                  orderItems:
                    type: array
                    description: List of items to confirm within the order
                    items:
                      type: object
                      properties:
                        orderItemId:
                          type: string
                          description: Unique identifier for the specific item in the order
                        quantity:
                          type: integer
                          description: Quantity of this bag item to confirm
                required:
                  - orderId
      responses:
        '200':
          description: Order confirmation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                payloadCount: 2
                successCount: 2
                failedCount: 0
                status: SUCCESS
                errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/invoiceUpdate:
    post:
      operationId: UpdateInvoice
      tags:
        - Orders
      summary: Update Invoice
      description: >-
        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"`
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/InvoiceUpdateRequest'
      responses:
        '200':
          description: Invoice update or credit note response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                payloadCount: 2
                successCount: 2
                failedCount: 0
                status: SUCCESS
                errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/awb:
    put:
      operationId: UpdateAWB
      tags:
        - Orders
      summary: Update AWB
      description: >
        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.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  awbNumber:
                    type: string
                    description: Air Way Bill number for the shipment
                  courierName:
                    type: string
                    description: Courier partner's name
                  orderId:
                    type: string
                    description: Unique identifier of the order
                  autoDispatch:
                    type: boolean
                    enum:
                      - false
                      - true
                    description: >-
                      When true, auto-transitions order from `dp_assigned` →
                      `bag_picked` state on Fynd OMS
                required:
                  - awbNumber
                  - courierName
                  - orderId
                  - autoDispatch
      responses:
        '200':
          description: Successful AWB update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      payload_count: 5
                      success_count: 5
                      failed_count: 0
                      errors: []
                    meta:
                      trace_id: 766199ba-df9a-11ef-bc17-6b1b0369fe3a
                      time: '2025-01-31T11:43:18.672+05:30'
                      status: SUCCESS
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Example400:
                  summary: 400 Bulk Limit
                  value:
                    data:
                      payload_count: 32
                      success_count: 0
                      failed_count: 32
                      errors:
                        - message:
                            - errors: >-
                                Request exceeds maximum allowed limit of 20
                                orders per bulk update. Please reduce the number
                                of orders and try again.
                    meta:
                      trace_id: 59c39cda-dfd3-11ef-bdad-f131b2a3964e
                      time: '2025-01-31T18:30:30.979+05:30'
                      status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/pack:
    post:
      operationId: PackOrder
      tags:
        - Orders
      summary: Order Pack
      description: |
        Marks unfulfilled orders as packed, readying them for dispatch.
          > Limits update of 20 orders per request. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order for which the order pack
                      call needs to be pushed to Fynd
      responses:
        '200':
          description: Order packing response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                payloadCount: 2
                successCount: 2
                failedCount: 0
                status: SUCCESS
                errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/courierDetails:
    post:
      operationId: GetCourierDetails
      tags:
        - Orders
      summary: Courier Details
      description: |
        Retrieve courier information for specific orders.
          > Limits update of 20 orders per request.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order for which the courier
                      details need to be fetched
      responses:
        '200':
          description: Courier details response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CourierDetailsResponse'
              examples:
                Example200:
                  summary: 200 Success
                  value:
                    - courierName: FyndTest
                      courierCode: FyndTest
                      awbNumber:
                        - '942413151341513'
                      additionalInfo: You can add additional info here
                      orderId: '17788083923861469968'
                    - courierName: FyndTest
                      courierCode: FyndTest
                      awbNumber:
                        - '842413151341513'
                      additionalInfo: You can add additional info here
                      orderId: '17888083923861469000'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/labels:
    post:
      operationId: GetShippingLabel
      tags:
        - Orders
      summary: Shipping Label
      description: >
        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. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order for which the shipping
                      label need to be fetched
      responses:
        '200':
          description: Returns shipping label PDF
          content:
            application/pdf:
              schema:
                type: string
                format: pdf
              examples:
                PdfResponse:
                  summary: 200 Success
                  value: As a response, the shipping label PDF will be the output.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/invoice:
    post:
      operationId: FetchCustomerInvoice
      tags:
        - Orders
      summary: Customer Invoice
      description: >
        Generate and retrieve a customer invoice (PDF) for orders ready for
        dispatch.
          > Limits update of 20 orders per request. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order for which the invoice
                      needs to be fetched from Fynd
      responses:
        '200':
          description: Returns a customer invoice PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              examples:
                PdfResponse:
                  summary: 200 Success
                  value: As a response, the customer invoice PDF will be the output.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/dispatch:
    post:
      operationId: DispatchOrder
      tags:
        - Orders
      summary: Order Dispatch
      description: >
        Mark the order(s) as dispatched; indicating it has  been handed over to
        the delivery partner.
          > Limits update of 20 orders per request. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order for which the order
                      dispatch call needs to be pushed to Fynd
                  orderItems:
                    type: array
                    items:
                      type: object
                      properties:
                        orderItemId:
                          type: string
                          description: Unique identifier of the order item
                        quantity:
                          type: integer
                          description: Quantity to be dispatched
      responses:
        '200':
          description: Order dispatch response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                payloadCount: 2
                successCount: 2
                failedCount: 0
                status: SUCCESS
                errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/status:
    put:
      operationId: UpdateShipmentStatus
      tags:
        - Orders
      summary: Update Shipment Status
      description: >
        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` → `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. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: Identifier of the order to update
                  orderStatus:
                    type: string
                    description: Next order status
                    enum:
                      - bag_picked
                      - delivery_done
                      - rto_bag_delivered
                      - return_bag_in_transit
                      - return_bag_delivered
                  meta:
                    type: object
                    description: Additional metadata for the update
                    properties:
                      remark:
                        type: string
                        description: Any remark or note
                      dpLocation:
                        type: string
                        description: Courier location
                      promised_delivery_date:
                        type: string
                        description: Promised date for final delivery
                      estimated_delivery_date:
                        type: string
                        description: Estimated date for final delivery
                required:
                  - orderId
                  - orderStatus
      responses:
        '200':
          description: Successful shipment status update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Success:
                  summary: 200 Success
                  value:
                    data:
                      payload_count: 2
                      success_count: 2
                      failed_count: 0
                      errors: []
                    meta:
                      trace_id: db6dfa6b-df9a-11ef-bc17-2fcac2e9681c
                      time: '2025-01-31T11:46:07.751+05:30'
                      status: SUCCESS
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
              examples:
                Example400:
                  summary: 400 Bulk Limit
                  value:
                    data:
                      payload_count: 32
                      success_count: 0
                      failed_count: 32
                      errors:
                        - message:
                            - errors: >-
                                Request exceeds maximum allowed limit of 20
                                orders per bulk update. Please reduce the number
                                of orders and try again
                    meta:
                      trace_id: 59c39cda-dfd3-11ef-bdad-f131b2a3964e
                      time: '2025-01-31T18:30:30.979+05:30'
                      status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
  /oms/v3/shipment/return:
    post:
      operationId: UpdateReturnAndQC
      tags:
        - Returns
      summary: Update Return & QC
      description: >
        Accept returns after QC checks while marking them as `return_accepted`
        on Fynd. 

          **Note:** Post finalizing bag items that pass inspection, the associated credit note can be 
          generated using the Update Invoice/Credit Note endpoint where `"invoiceType": "return"`.
          > Limits update of 20 returns per request. 
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  orderId:
                    type: string
                    description: >-
                      Unique identifier for the order that is to be accepted
                      after a quality control check by the seller
                  orderItems:
                    type: array
                    items:
                      type: object
                      properties:
                        orderItemId:
                          type: string
                          description: List of bag items to accept within the return
                        quantity:
                          type: integer
                          description: Quantity of bag items accepted in the return
                        reasonCode:
                          type: string
                          description: QC code or reason for acceptance or rejection
                required:
                  - orderId
      responses:
        '200':
          description: Return acceptance response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                Example200Success:
                  summary: 200 Success
                  value:
                    payloadCount: 1
                    successCount: 1
                    failedCount: 0
                    status: SUCCESS
                    errors: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Example400:
                  summary: 400 Bad Request
                  value:
                    error: Bad Request
                    status: FAILED
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
              examples:
                Unauthorized:
                  summary: 401 Unauthorized
                  value:
                    errors:
                      - message: Invalid access token. Please check
                    meta:
                      time: '2025-01-31T08:27:27.408+00:00'
                      status: access denied
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-access-token
  schemas:
    Error:
      type: object
      description: Schema for generic error responses
      properties:
        error:
          type: string
          description: Error message describing the failure reason
        status:
          type: string
          description: Status of the API call
      required:
        - error
        - status
    AuthResponse:
      type: object
      description: Schema for successful authorization response
      properties:
        access_token:
          type: string
          description: Token used for API authorization
        status:
          type: string
          description: Status of the API call
      required:
        - access_token
        - status
    Error401:
      type: object
      description: Schema for unauthorized access errors
      properties:
        errors:
          type: array
          description: List of error messages
          items:
            type: object
            properties:
              message:
                type: string
                description: Explanation of the unauthorized error
        meta:
          type: object
          description: Additional metadata for the 401 error
          properties:
            time:
              type: string
              format: date-time
              description: Timestamp of the error.
            status:
              type: string
              description: Status of the API call
    Error404:
      type: object
      description: Schema for Not Found (404) errors
      properties:
        code:
          type: string
          description: Error code name
          example: Not-Found
        message:
          type: string
          description: Details of the missing resource
          example: The requested resource was not found
        type:
          type: string
          description: Type/category of the error
          example: Global-Error
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the error occurred
          example: '2025-01-30T07:40:05.123Z'
    Error500:
      type: object
      description: Schema for internal server errors
      properties:
        code:
          type: string
          description: Error code name
          example: Server-Error
        message:
          type: string
          description: Details of the missing resource
          example: orderStatus or orderId is required
        type:
          type: string
          description: Type/category of the error
          example: Global-Error
        timestamp:
          type: string
          format: date-time
          description: Timestamp of when the error occurred
          example: '2025-01-30T07:40:05.123Z'
    OperationResponse:
      type: object
      description: Schema for operation status details
      properties:
        data:
          type: object
          description: Response data regarding payload processing
          properties:
            payload_count:
              type: integer
              description: Number of payload items in the request
            success_count:
              type: integer
              description: Number of items successfully processed
            failed_count:
              type: integer
              description: Number of items that failed
            errors:
              type: array
              description: List of error details for failed items
              items:
                type: object
                properties:
                  sku:
                    type: string
                    description: Product SKU related to the error
                  location_id:
                    type: string
                    description: Location ID related to the error
                  message:
                    type: string
                    description: Error message describing the failure
                  id:
                    type: string
                    description: Additional identifier for the error instance
        meta:
          type: object
          description: Metadata about the operation's result
          properties:
            ack_id:
              type: string
              description: Acknowledgment ID for the response
            time:
              type: string
              description: ISO 8601 formatted timestamp
            status:
              type: string
              enum:
                - SUCCESS
                - WARNING
                - FAIL
              description: Status of the API call
    SuccessResponse:
      type: object
      description: Schema for a fully successful bulk operation
      properties:
        payloadCount:
          type: integer
          description: Number of payloads in the request
        successCount:
          type: integer
          description: Number of successfully processed payloads
        failedCount:
          type: integer
          description: Number of payloads that failed
        status:
          type: string
          description: Status of the API call
        errors:
          type: array
          description: Empty if everything succeeded
          items:
            type: object
    ProductCount:
      type: object
      description: Schema for product count response
      properties:
        data:
          type: object
          description: Data object containing listing counts
          properties:
            listing_count:
              type: integer
              description: Count of listings
        meta:
          type: object
          description: Response metadata for product count
          properties:
            ack_id:
              type: string
              description: Request acknowledgment ID
            integrationId:
              type: string
              description: Integration identifier
            time:
              type: string
              description: ISO 8601 formatted timestamp
            status:
              type: string
              description: Status of the API call
    ProductListing:
      type: object
      description: Schema for product listing responses
      properties:
        data:
          type: array
          description: Array of product listing objects
          items:
            type: object
            properties:
              sku:
                type: string
                description: Seller Identifier of the product
              quantity:
                type: integer
                description: Stock quantity
              location_id:
                type: string
                description: Location/store identifier
              esp:
                type: number
                format: float
                description: Effective selling price
              mrp:
                type: number
                format: float
                description: Maximum retail price
        meta:
          type: object
          description: Response metadata for product listings
          properties:
            ack_id:
              type: string
              description: Request acknowledgment ID
            integrationId:
              type: string
              description: Integration identifier
            time:
              type: string
              description: ISO 8601 formatted timestamp
            status:
              type: string
              description: Status of the API request
    PriceUpdate:
      type: array
      description: Array of price update objects
      items:
        type: object
        properties:
          location_id:
            type: string
            description: Location identifier for the SKU
          sku:
            type: string
            description: SKU for the item
          esp:
            type: number
            description: Effective selling price
          mrp:
            type: number
            description: Maximum retail price
          currency:
            type: string
            description: Currency code (e.g., 'INR')
        required:
          - location_id
          - sku
          - esp
          - mrp
          - currency
    InventoryUpdate:
      type: array
      description: Array of inventory update objects
      items:
        type: object
        properties:
          location_id:
            type: string
            description: Store code or location identifier
          sku:
            type: string
            description: Store Identifier of the product
          quantity:
            type: integer
            description: Quantity of the SKU in that location
        required:
          - location_id
          - sku
          - quantity
    OrderItem:
      type: object
      description: Schema for an item within an order
      properties:
        title:
          type: string
          description: Short descriptive title
        orderItemId:
          type: string
          description: Unique identifier for the order item
        quantity:
          type: integer
          description: Quantity of this item
        gstDetails:
          type: object
          description: GST tax details for the item
          properties:
            taxPercentage:
              type: object
              properties:
                sgst:
                  type: number
                cgst:
                  type: number
            taxAmount:
              type: object
              properties:
                sgst:
                  type: number
                cgst:
                  type: number
        locationCode:
          type: string
          description: Location code of the store or warehouse
        status:
          type: string
          description: Status of the API call
    OrderResponse:
      type: object
      description: Schema for the overall order/return response
      properties:
        id:
          type: string
          description: Unique identifier for the shipment or order
        forwardId:
          type: string
          description: Forward ID if this is a return, else same as shipment id
        marketplaceOrderId:
          type: string
          description: Marketplace-provided order ID if applicable
        shippingAddress:
          type: object
          properties:
            addressLine1:
              type: string
            phone:
              type: string
            city:
              type: string
            email:
              type: string
            name:
              type: string
            pincode:
              type: string
            state:
              type: string
            country:
              type: string
        orderItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        orderStatus:
          type: string
          description: Current status of the entire order
        orderDate:
          type: string
          format: date-time
          description: Timestamp when the order was placed
        orderingChannel:
          type: string
          description: Sales channel like FYND, JIOMART, ECOMM, etc.
    InvoiceUpdateRequest:
      type: object
      description: Schema for invoice or credit note posting
      properties:
        orderId:
          type: string
          description: Shipment Id of the order to be invoiced
        invoiceNumber:
          type: string
          description: Unique invoice reference number
        invoiceType:
          type: string
          description: >-
            Type of invoice (Either `sale` for the forward order invoice series
            or `return` for the customer return credit note)
        invoiceQrCode:
          type: string
          description: QR code data for the invoice
        irnNumber:
          type: string
          description: Invoice Reference Number for e-invoicing
        signedInvoice:
          type: string
          description: Digitally signed invoice data
        ackNumber:
          type: string
          description: Acknowledgment number from tax authority
        ackDate:
          type: string
          description: Date of acknowledgment receipt
        orderItems:
          type: array
          description: List of items included in the invoice
          items:
            type: object
            properties:
              orderItemId:
                type: string
                description: Unique identifier of the bag item
              quantity:
                type: integer
                description: Quantity of items being invoiced
              imeiSerialNumber:
                type: array
                description: List of IMEI or serial numbers for the items
                items:
                  type: string
        packages:
          type: array
          description: >-
            Meta data for packaging if applicable; overwrites the existing
            package dimensions
          items:
            type: object
            properties:
              packageId:
                type: string
                description: Unique identifier of the package
              packageLengthCm:
                type: number
                description: Length of package in centimeters
              packageWidthCm:
                type: number
                description: Width of package in centimeters
              packageHeightCm:
                type: number
                description: Height of package in centimeters
              packageWeightGms:
                type: number
                description: Weight of package in grams
      required:
        - orderId
        - invoiceNumber
        - invoiceType
    CourierDetailsResponse:
      type: object
      description: Schema for courier details of a shipment
      properties:
        courierName:
          type: string
          description: Name of the courier service provider
        courierCode:
          type: string
          description: Fynd unique code identifying the courier partner
        awbNumber:
          type: array
          description: List of airway bill numbers for tracking
          items:
            type: string
        additionalInfo:
          type: string
          description: Any extra information about the shipment
        orderId:
          type: string
          description: Shipment ID of the order for which the courier has been assigned
