> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Global search across Customers, Orders, and Products

> Search across Customers, Orders, and Products using search. Each `content.results[]` entry is a `GlobalSearchResult`. Read `indexUid` to interpret `hits`: customer index entries are `GlobalSearchCustomerHit`, order index entries are `GlobalSearchOrder`, product index entries are `GlobalSearchProduct`.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-admin.json get /store/search
openapi: 3.2.0
info:
  title: CE Admin APIs
  version: '1.0'
  summary: Comprehensive admin interface for managing your e-commerce platform
  description: >-
    Complete administrative API suite for Commerce Engine, providing powerful
    tools to manage products, orders, customers, inventory, analytics, and
    system configuration. Designed for administrators and backend integrations
    requiring full platform control.
  license:
    name: All Rights Reserved
    url: https://www.commercengine.io/contact-us
  contact:
    email: support@commercengine.io
    url: https://www.commercengine.io/contact-us
    name: Support
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/admin
    description: Staging Server
    variables:
      store_id:
        default: store_id
        description: Store ID
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/admin
    description: Prod Server
    variables:
      store_id:
        default: store_id
        description: Store ID
security:
  - Authorization: []
tags:
  - name: section-catalog
    summary: Catalog
    kind: nav
  - name: Products
    description: >-
      Create and update products; manage their channels and category
      assignments, and list SKUs.
    summary: Products
    kind: nav
    parent: section-catalog
  - name: Variants
    description: Create, read and update product variants individually or in bulk.
    summary: Variants
    kind: nav
    parent: section-catalog
  - name: Categories
    description: Manage catalog categories and the attributes assigned to them.
    summary: Categories
    kind: nav
    parent: section-catalog
  - name: Product attributes
    description: Define product attributes and the attribute sets that organize them.
    summary: Product attributes
    kind: nav
    parent: section-catalog
  - name: Inventory
    description: >-
      Read stock and inventory activity, update inventory, and record stock-in
      and stock-out movements.
    summary: Inventory
    kind: nav
    parent: section-catalog
  - name: Reviews
    description: Read, moderate and remove product reviews.
    summary: Reviews
    kind: nav
    parent: section-catalog
  - name: Media
    description: >-
      Request file uploads, manage uploaded files, and organize them into
      folders.
    summary: Media
    kind: nav
    parent: section-catalog
  - name: Catalog jobs
    description: Create catalog processing jobs and follow their status.
    summary: Catalog jobs
    kind: nav
    parent: section-catalog
  - name: section-customers
    summary: Customers
    kind: nav
  - name: Customers
    description: >-
      Create and update customers, view their details and activity, and manage
      profile images.
    summary: Customers
    kind: nav
    parent: section-customers
  - name: Users
    description: List the users attached to a customer and activate or deactivate them.
    summary: Users
    kind: nav
    parent: section-customers
  - name: Customer attributes
    description: Define customer attributes and manage the values assigned to customers.
    summary: Customer attributes
    kind: nav
    parent: section-customers
  - name: Customer groups
    description: Configure the customer groups available in the store.
    summary: Customer groups
    kind: nav
    parent: section-customers
  - name: Addresses
    description: Read and manage a customer’s saved addresses.
    summary: Addresses
    kind: nav
    parent: section-customers
  - name: Bank accounts
    description: Read and manage a customer’s bank accounts.
    summary: Bank accounts
    kind: nav
    parent: section-customers
  - name: KYC documents
    description: Configure the store’s KYC requirements and manage customer documents.
    summary: KYC documents
    kind: nav
    parent: section-customers
  - name: Visitors
    description: >-
      Read anonymous visitor profiles, their activity and their attribute
      values.
    summary: Visitors
    kind: nav
    parent: section-customers
  - name: Loyalty
    description: >-
      Configure loyalty programs, manage membership tiers, and inspect or record
      point activity.
    summary: Loyalty
    kind: nav
    parent: section-customers
  - name: Credit
    description: Set credit-line eligibility and read customer credit balances.
    summary: Credit
    kind: nav
    parent: section-customers
  - name: Mandates
    description: >-
      Inspect customer payment mandates and debit schedules, and pause, resume
      or revoke a mandate.
    summary: Mandates
    kind: nav
    parent: section-customers
  - name: Segments
    description: >-
      Manage customer segments, their members and associated advertising
      audiences.
    summary: Segments
    kind: nav
    parent: section-customers
  - name: section-shopping
    summary: Shopping
    kind: nav
  - name: Carts
    description: List abandoned carts for follow-up.
    summary: Carts
    kind: nav
    parent: section-shopping
  - name: Coupons & promotions
    description: Manage coupons, coupon codes and promotions, and inspect their usage.
    summary: Coupons & promotions
    kind: nav
    parent: section-shopping
  - name: section-orders
    summary: Orders
    kind: nav
  - name: Orders
    description: >-
      Read and update orders, accept or cancel them, check stock, and follow
      order activity.
    summary: Orders
    kind: nav
    parent: section-orders
  - name: Invoices
    description: List order invoices and retrieve an order’s invoice or receipt.
    summary: Invoices
    kind: nav
    parent: section-orders
  - name: Returns
    description: Read customer return requests and approve or reject them.
    summary: Returns
    kind: nav
    parent: section-orders
  - name: Shipments
    description: >-
      Create and manage shipments, follow delivery activity, and handle
      replacements and shortfalls.
    summary: Shipments
    kind: nav
    parent: section-orders
  - name: section-payments
    summary: Payments
    kind: nav
  - name: Order payments
    description: >-
      Create and inspect payment requests, verify order payments, and cancel or
      mark a payment paid.
    summary: Order payments
    kind: nav
    parent: section-payments
  - name: Refunds
    description: Estimate and issue refunds, or mark an order refund paid or forfeited.
    summary: Refunds
    kind: nav
    parent: section-payments
  - name: Payment exceptions
    description: Inspect payment exceptions and resolve them.
    summary: Payment exceptions
    kind: nav
    parent: section-payments
  - name: Payment methods
    description: Configure manual payment methods and list available payment options.
    summary: Payment methods
    kind: nav
    parent: section-payments
  - name: Seller payouts
    description: >-
      Configure seller payouts and manage invoices, adjustments, charges and
      payout batches.
    summary: Seller payouts
    kind: nav
    parent: section-payments
  - name: section-marketplace
    summary: Marketplace
    kind: nav
  - name: Marketplace catalog
    description: Inspect and publish marketplace products, variants, reviews and inventory.
    summary: Marketplace catalog
    kind: nav
    parent: section-marketplace
  - name: Marketplace listings
    description: List, synchronize and remove the store’s product listings on marketplaces.
    summary: Marketplace listings
    kind: nav
    parent: section-marketplace
  - name: Marketplace settings
    description: >-
      Read marketplace configuration and configure category schemas and
      attributes.
    summary: Marketplace settings
    kind: nav
    parent: section-marketplace
  - name: Sellers
    description: Manage the sellers a customer is authorized to buy from.
    summary: Sellers
    kind: nav
    parent: section-marketplace
  - name: section-fulfillment
    summary: Fulfillment
    kind: nav
  - name: Shipping methods
    description: Configure shipping methods and costs, and check courier serviceability.
    summary: Shipping methods
    kind: nav
    parent: section-fulfillment
  - name: Shipping boxes
    description: Manage shipping boxes and read the boxes available for a product.
    summary: Shipping boxes
    kind: nav
    parent: section-fulfillment
  - name: Shipping zones
    description: Create, read and maintain shipping zones.
    summary: Shipping zones
    kind: nav
    parent: section-fulfillment
  - name: Warehouses
    description: Create, read and maintain the store’s warehouses.
    summary: Warehouses
    kind: nav
    parent: section-fulfillment
  - name: section-point-of-sale
    summary: Point of sale
    kind: nav
  - name: Devices
    description: Manage POS devices, generate pairing codes and revoke devices.
    summary: Devices
    kind: nav
    parent: section-point-of-sale
  - name: POS users
    description: Manage staff accounts used at the point of sale.
    summary: Staff
    kind: nav
    parent: section-point-of-sale
  - name: POS roles
    description: Manage POS roles and inspect available permissions.
    summary: Roles & permissions
    kind: nav
    parent: section-point-of-sale
  - name: section-store
    summary: Store
    kind: nav
  - name: Store
    description: Read and update the store configuration.
    summary: Store
    kind: nav
    parent: section-store
  - name: Locations
    description: List countries, states and pincodes.
    summary: Locations
    kind: nav
    parent: section-store
  - name: Notifications
    description: >-
      Manage notification templates and store or customer notification
      preferences.
    summary: Notifications
    kind: nav
    parent: section-store
  - name: Downloads
    description: Request data downloads and follow download jobs.
    summary: Downloads
    kind: nav
    parent: section-store
  - name: Search
    description: Search customers, orders and products across the store.
    summary: Search
    kind: nav
    parent: section-store
  - name: Filter options
    description: >-
      Retrieve the available filters for resource lists in the administration
      interface.
    summary: Filter options
    kind: nav
    parent: section-store
  - name: section-integrations
    summary: Integrations
    kind: nav
  - name: Catalog integrations
    description: Request catalog synchronization and inspect sync results and activity.
    summary: Catalog integrations
    kind: nav
    parent: section-integrations
  - name: Service providers
    description: Configure service providers and test their connections.
    summary: Service providers
    kind: nav
    parent: section-integrations
  - name: Webhooks
    description: >-
      Manage webhook subscriptions, rotate their secrets and send test
      deliveries.
    summary: Webhooks
    kind: nav
    parent: section-integrations
  - name: Webhook deliveries
    description: >-
      Inspect webhook delivery logs, retry deliveries and replay events to a
      subscription.
    summary: Webhook deliveries
    kind: nav
    parent: section-integrations
  - name: Events
    description: >-
      Browse recorded events and the event types available for webhook
      subscriptions.
    summary: Events
    kind: nav
    parent: section-integrations
  - name: Live updates
    description: Read the store’s live event stream and global state.
    summary: Live updates
    kind: nav
    parent: section-integrations
  - name: section-analytics
    summary: Analytics
    kind: nav
  - name: Analytics
    description: Query analytics data, read charts and inspect visitor sessions and events.
    summary: Analytics
    kind: nav
    parent: section-analytics
  - name: Metrics
    description: >-
      Read aggregate metrics for catalog, customers, orders, payments,
      fulfillment and webhooks.
    summary: Metrics
    kind: nav
    parent: section-analytics
paths:
  /store/search:
    get:
      tags:
        - Search
      summary: Global search across Customers, Orders, and Products
      description: >-
        Search across Customers, Orders, and Products using search. Each
        `content.results[]` entry is a `GlobalSearchResult`. Read `indexUid` to
        interpret `hits`: customer index entries are `GlobalSearchCustomerHit`,
        order index entries are `GlobalSearchOrder`, product index entries are
        `GlobalSearchProduct`.
      operationId: global-search
      parameters:
        - name: attributesToRetrieve
          in: query
          description: JSON-encoded option.
          schema:
            type: string
        - name: attributesToSearchOn
          in: query
          description: JSON-encoded option.
          schema:
            type: string
        - name: facets
          in: query
          description: JSON-encoded option.
          schema:
            type: string
        - name: filter
          in: query
          description: >-
            search filter expression, e.g. `id=01KXQD8EACBDCEM5Y8HTJ3Q71T`.
            Returns `400` if it references an attribute that is not filterable.
          required: false
          schema:
            type: string
        - name: include_parent_product
          in: query
          schema:
            type: boolean
        - name: index
          in: query
          description: Search index to query
          required: false
          schema:
            enum:
              - Customers
              - Orders
              - Products
        - name: limit
          in: query
          description: >-
            Results per page. Values below 1 use 1; values above 500 return 400.
            Non-integer input returns 400.
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
        - name: matchingStrategy
          in: query
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: search
          in: query
          description: Search query string
          required: false
          schema:
            type: string
            default: ''
        - name: showMatchesPosition
          in: query
          schema:
            type: boolean
        - name: sort
          in: query
          description: JSON-encoded option.
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  content:
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/GlobalSearchResult'
                    type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    GlobalSearchResult:
      title: GlobalSearchResult
      description: >-
        One Search index result. `hits` entries match `GlobalSearchProduct` when
        `indexUid` is the products index, `GlobalSearchOrder` for orders, and
        `GlobalSearchCustomerHit` for customers.
      type: object
      properties:
        indexUid:
          type: string
        hits:
          description: >-
            Index documents. Shape depends on `indexUid`:
            `GlobalSearchCustomerHit`, `GlobalSearchOrder`, or
            `GlobalSearchProduct`.
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/GlobalSearchCustomerHit'
              - $ref: '#/components/schemas/GlobalSearchOrder'
              - $ref: '#/components/schemas/GlobalSearchProduct'
        facetDistribution:
          description: Search facet counts keyed by attribute, then facet value.
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
        facetStats:
          description: Search numeric facet min/max per attribute.
          type: object
          additionalProperties:
            type: object
            properties:
              min:
                type: number
              max:
                type: number
        query:
          type: string
        processingTimeMs:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        offset:
          type: integer
          format: int32
        estimatedTotalHits:
          type: integer
          format: int32
    GlobalSearchCustomerHit:
      title: GlobalSearchCustomerHit
      description: Customer document from the Search Customers index.
      type: object
      properties:
        id:
          type: string
          readOnly: true
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        full_name:
          type:
            - string
            - 'null'
          readOnly: true
        profile_image_url:
          type:
            - string
            - 'null'
          readOnly: true
        country_code:
          type: string
        phone:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        is_whatsapp_verified:
          type: boolean
          readOnly: true
        is_verified:
          type: boolean
          readOnly: true
        status:
          description: >-
            Customer status as indexed. Often `active` or `inactive`; the index
            may contain other values.
          type:
            - string
            - 'null'
        kyc_status:
          $ref: '#/components/schemas/KycStatus'
        customer_group_id:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        attributes:
          description: >-
            The customer's attribute values, by attribute slug: `custom` and
            `system` attributes that have a value. Searchable.
          type: object
          additionalProperties: true
        kyc_document_numbers:
          description: >-
            The numbers of the customer's KYC documents, whatever their status.
            Searchable.
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        modified_at:
          type: string
          format: date-time
          readOnly: true
        last_seen:
          type:
            - string
            - 'null'
          readOnly: true
        business:
          description: '`null` when the customer is not registered as a business.'
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BusinessInfo'
        address:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CustomerAddress'
        segments:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSegment'
      x-tags:
        - Store
    GlobalSearchOrder:
      title: GlobalSearchOrder
      type: object
      properties:
        billing_address:
          $ref: '#/components/schemas/OrderAddress'
        cart_id:
          type:
            - string
            - 'null'
        coupon_code:
          type:
            - string
            - 'null'
        coupon_id:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        credit_balance_used:
          type: number
          format: double
        currency:
          type: object
          properties:
            name:
              type: string
            code:
              type: string
            symbol:
              type: string
        customer_id:
          type: string
        customer_note:
          type:
            - string
            - 'null'
        fulfillment_type:
          enum:
            - collect-in-store
            - delivery
        grand_total:
          type: number
          format: double
        id:
          type: string
        loyalty_point_earned:
          type: number
          format: double
        loyalty_point_redeemed:
          type: number
          format: double
        metadata:
          type: object
          additionalProperties:
            type: string
        modified_at:
          type: string
          format: date-time
        on_subscription:
          type: boolean
        order_date:
          type: string
          format: date-time
        order_items_count:
          type: integer
        order_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        order_number:
          type: string
        payment_status:
          $ref: '#/components/schemas/PaymentStatus'
        payment_success_date:
          type:
            - string
            - 'null'
          format: date-time
        sales_channel:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            type:
              type: string
          required:
            - id
            - name
            - type
        shipping_address:
          $ref: '#/components/schemas/OrderAddress'
        status:
          $ref: '#/components/schemas/OrderStatus'
        to_be_paid:
          type: number
          format: double
      x-tags:
        - Orders
    GlobalSearchProduct:
      title: GlobalSearchProduct
      type: object
      properties:
        active:
          type: boolean
        associated_options:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedOption'
        attribute:
          type:
            - object
            - 'null'
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/ProductAttribute'
        categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
                readOnly: true
              description:
                type:
                  - string
                  - 'null'
                readOnly: true
              slug:
                type: string
                readOnly: true
              parent_category_id:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_count:
                type: integer
                readOnly: true
              active:
                type: boolean
                readOnly: true
        category_ids:
          type: array
          items:
            type: string
        customer_group_id:
          type:
            - string
            - 'null'
        has_variant:
          type: boolean
        hsn_code:
          type:
            - string
            - 'null'
        id:
          description: product id
          type: string
          readOnly: true
        images:
          type: array
          items:
            $ref: '#/components/schemas/ProductImage'
        is_featured:
          type: boolean
        name:
          type: string
          maxLength: 128
        on_offer:
          type: boolean
        on_promotion:
          type: boolean
        on_subscription:
          type: boolean
        packing:
          $ref: '#/components/schemas/ProductPackaging'
        price:
          type:
            - number
            - 'null'
          format: double
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/ProductPricing'
        product_id:
          type: string
        product_name:
          type: string
        product_slug:
          type: string
          maxLength: 128
        variant_slug:
          type:
            - string
            - 'null'
          maxLength: 128
        _rankingScore:
          description: Search relevance score for the hit.
          type: number
          format: double
        product_type:
          enum:
            - physical
            - digital
            - bundle
        promotion:
          $ref: '#/components/schemas/ProductPromotion'
        rating:
          type:
            - number
            - 'null'
          format: float
        raw_attributes:
          type:
            - object
            - 'null'
          additionalProperties: true
        reviews_count:
          description: >-
            Number of approved reviews; pending, rejected and archived reviews
            are excluded.
          type: integer
          format: int32
          readOnly: true
        reviews_rating_sum:
          description: >-
            Sum of approved review ratings, preserving fractional ratings. Zero
            when there are no approved reviews. Divide by reviews_count when
            nonzero to compute the average.
          type: number
          format: double
          readOnly: true
        sales_channels:
          type: array
          items:
            $ref: '#/components/schemas/SalesChannel'
        seo:
          $ref: '#/components/schemas/Seo'
        shipping:
          oneOf:
            - $ref: '#/components/schemas/ProductShipping'
            - type: 'null'
        short_description:
          type:
            - string
            - 'null'
          maxLength: 256
        sku:
          type: string
          maxLength: 64
        slug:
          type: string
          maxLength: 128
        status:
          $ref: '#/components/schemas/ProductStatus'
        stock_available:
          type: boolean
        subscription:
          type: array
          items:
            $ref: '#/components/schemas/ProductSubscription'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        variant_id:
          type:
            - string
            - 'null'
          maxLength: 128
        variant_name:
          type:
            - string
            - 'null'
          maxLength: 128
      x-tags:
        - Catalog
    KycStatus:
      description: >-
        KYC progress for a customer. `document_pending` means required documents
        have not been uploaded; `submitted` and `submitted_for_approval` mean
        they are awaiting review.
      enum:
        - pending
        - document_pending
        - submitted
        - submitted_for_approval
        - approved
        - rejected
    BusinessInfo:
      title: BusinessInfo
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
        business_type:
          description: >-
            Stored customer business type. Existing records may contain free
            text, including a default customer group name from storefront
            signup. Newly supplied values: sole_proprietorship, partnership,
            private_limited, public_limited, public_listed, state_owned,
            charity, individual, llp, other. A value here does not imply the
            customer is a registered business.
          type:
            - string
            - 'null'
        pan_number:
          type:
            - string
            - 'null'
        gstin:
          type:
            - string
            - 'null'
        is_registered_under_gst:
          type: boolean
      x-tags:
        - Customers
    CustomerAddress:
      title: CustomerAddress
      type: object
      required:
        - first_name
        - phone
        - email
        - address_line1
        - pincode
        - city
        - state
        - country
      properties:
        id:
          type: string
          readOnly: true
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: "Two-letter code begin with a plus sign prefix that identifies different countries. By default it will be +91 if not provided.\r\n"
          type: string
        phone:
          description: 10 digit phone number without country code.
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        address_line1:
          type:
            - string
            - 'null'
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          description: Country name. `null` when the address was saved without one.
          type:
            - string
            - 'null'
        gstin:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        business_name:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        is_default_shipping:
          type: boolean
        is_default_billing:
          type: boolean
        created_at:
          type: string
          format: date-time
          readOnly: true
        modified_at:
          type: string
          format: date-time
          readOnly: true
        is_primary:
          type: boolean
          readOnly: true
      examples: []
      x-tags:
        - Customers
    CustomerSegment:
      title: CustomerSegment
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      x-tags:
        - Customers
    OrderAddress:
      title: OrderAddress
      description: Address snapshot captured at checkout for an order or invoice.
      type: object
      required:
        - first_name
        - phone
        - email
        - address_line1
        - pincode
        - city
        - state
        - country
      properties:
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: Phone country calling code, e.g. +91.
          type:
            - string
            - 'null'
        phone:
          description: 10 digit phone number without country code.
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        address_line1:
          type:
            - string
            - 'null'
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        gstin:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        business_name:
          description: Use in shipping details only for third party.
          type:
            - string
            - 'null'
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
      x-tags:
        - Orders
    OrderItem:
      title: OrderItem
      type: object
      required:
        - sku
        - quantity
      properties:
        product_id:
          type: string
          readOnly: true
        product_name:
          type: string
          readOnly: true
        slug:
          description: >-
            Slug of the thing actually ordered — the variant's slug when the
            item has a variant, otherwise the product's.
          type: string
          readOnly: true
        product_slug:
          type:
            - string
            - 'null'
          readOnly: true
        variant_slug:
          description: Null or an empty string when the item has no variant.
          type:
            - string
            - 'null'
          readOnly: true
        product_type:
          $ref: '#/components/schemas/ProductType'
        product_image_url:
          type:
            - string
            - 'null'
          readOnly: true
        sku:
          type: string
        on_offer:
          type: boolean
          readOnly: true
        on_promotion:
          type: boolean
          readOnly: true
        on_subscription:
          type: boolean
        subscription_plan:
          type:
            - string
            - 'null'
        subscription_interval:
          type:
            - integer
            - 'null'
          readOnly: true
        subscription_frequency:
          type:
            - string
            - 'null'
          readOnly: true
        quantity:
          type: integer
        incremental_quantity:
          description: Step the quantity can be changed by.
          type: integer
          readOnly: true
        free_quantity:
          type: integer
          readOnly: true
        is_free_item:
          type: boolean
          readOnly: true
        selling_price:
          type: number
          format: double
          readOnly: true
        selling_price_excluding_tax:
          type: number
          format: double
          readOnly: true
        listing_price:
          type: number
          format: double
          readOnly: true
        price_including_tax:
          description: >-
            Whether `selling_price` and `listing_price` already include tax. A
            flag, not an amount.
          type: boolean
          readOnly: true
        promotion_discount_amount:
          type: number
          format: double
          readOnly: true
        promotion_discount_percent:
          type: number
          format: double
          readOnly: true
        coupon_discount_amount:
          type: number
          format: double
          readOnly: true
        coupon_discount_percent:
          type:
            - number
            - 'null'
          format: double
          readOnly: true
        tax_type:
          description: >-
            Tax type from product pricing; seller order copies can use lowercase
            values.
          type: string
          default: GST
          enum:
            - gst
            - GST
            - VAT
            - ECO
            - vat
            - eco
          readOnly: true
        tax_rate:
          type: number
          format: float
          readOnly: true
        tax_amount:
          type: number
          format: double
          readOnly: true
        hsncode:
          description: HSN code used for the item's tax treatment.
          type:
            - string
            - 'null'
          readOnly: true
        handling_charge_excluding_tax:
          type: number
          format: double
          readOnly: true
        handling_charge_including_tax:
          type: number
          format: double
        handling_charge_tax_rate:
          type: number
          format: double
        variant_id:
          type:
            - string
            - 'null'
        variant_name:
          type:
            - string
            - 'null'
        product_variant_id:
          type:
            - string
            - 'null'
          readOnly: true
        seller_id:
          description: >-
            Seller ID. This field is relevant for marketplace type stores only.
            Will return null for b2b and b2c type stores.
          type:
            - string
            - 'null'
        seller_detail:
          description: >-
            Seller detail information. This field is relevant for marketplace
            type stores only. Will return null for b2b and b2c type stores.
          oneOf:
            - $ref: '#/components/schemas/SellerBasicDetail'
            - type: 'null'
        seller_product_id:
          description: >-
            Seller's own product identifier. Relevant to marketplace stores
            only; `null` for b2b and b2c stores.
          type:
            - string
            - 'null'
          readOnly: true
        seller_variant_id:
          description: >-
            Seller's own variant identifier. Relevant to marketplace stores
            only; `null` for b2b and b2c stores.
          type:
            - string
            - 'null'
          readOnly: true
        attributes:
          description: Product attributes captured on the item at the time of the order.
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              id:
                type: string
              key:
                description: Attribute name in snake case.
                type: string
              name:
                type: string
              type:
                description: >-
                  Attribute type, e.g. `single-select`, `boolean`, `text`,
                  `multi-select`, `date`, `color`.
                type: string
              value:
                description: >-
                  The attribute value captured on the order item. Its JSON shape
                  follows the attribute type: strings for text, single-select
                  and date; booleans for boolean; lists for multi-select;
                  structured values for color.
          readOnly: true
        associated_options:
          description: >-
            Variant options, keyed by the option's snake-case key. `null` for
            items with no variant.
          type:
            - object
            - 'null'
          additionalProperties:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              value:
                type: string
          readOnly: true
      x-tags:
        - Orders
    PaymentStatus:
      title: PaymentStatus
      type: string
      enum:
        - pending
        - success
        - failed
        - partially_paid
        - refund_initiated
        - refunded
        - unsettled
        - settled
        - partially_settled
        - manual_review
        - debit_scheduled
        - collection_due
    OrderStatus:
      title: OrderStatus
      type: string
      enum:
        - draft
        - awaiting_approval
        - confirmed
        - schedule_requested
        - partially_scheduled
        - awaiting_shipment
        - shipped
        - partially_shipped
        - undelivered
        - partially_undelivered
        - return_to_origin
        - partially_return_to_origin
        - complete
        - partially_delivered
        - cancelled
        - pending
        - payment_failed
        - sent_to_store
        - ready_to_collect
        - processing
        - lost
    AssociatedOption:
      title: AssociatedOption
      type: object
      required:
        - attribute_id
        - attribute_value
      properties:
        attribute_id:
          type: string
        attribute_value:
          oneOf:
            - type: string
              description: >-
                Attributes with type of **single-select**, the value will be
                represented as a **string**.
            - $ref: '#/components/schemas/ColorObject'
              description: >-
                **Color** attributes will have their value represented as a
                color object, specifying the color details with name and
                hexcode.
        attribute_name:
          type: string
          readOnly: true
        attribute_type:
          enum:
            - single-select
            - color
          readOnly: true
        key:
          description: value in snake case.
          type: string
          readOnly: true
    ProductAttribute:
      title: ProductAttribute
      type: object
      properties:
        id:
          description: >-
            Attribute id as returned on SKU and search payloads; same as
            `attribute_id` on write.
          type: string
        name:
          description: Display name; same as `attribute_name` on write payloads.
          type: string
          readOnly: true
        type:
          description: Same as `attribute_type` on write payloads.
          type: string
          enum:
            - text
            - number
            - boolean
            - date
            - single-select
            - multi-select
            - color
          readOnly: true
        value:
          description: Resolved value; same as `attribute_value` on write payloads.
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
            - $ref: '#/components/schemas/ColorObject'
        is_visible:
          type: boolean
          readOnly: true
        is_filterable:
          type: boolean
          readOnly: true
        attribute_id:
          type: string
        attribute_name:
          type: string
          readOnly: true
        attribute_type:
          type: string
          enum:
            - text
            - number
            - boolean
            - date
            - single-select
            - multi-select
            - color
          readOnly: true
        attribute_value:
          oneOf:
            - type: string
              description: >-
                string value for attribute type **text**, **single select** and
                **date**.
            - type: number
              description: numeric value for attribute type number.
            - type: boolean
              description: true/false for attribute type boolean.
            - type: array
              description: for attribute type = multi-select
              items:
                type: string
            - $ref: '#/components/schemas/ColorObject'
              description: for attribute type = color
        key:
          description: Value in snake case.
          type: string
          readOnly: true
      examples: []
      x-tags:
        - Catalog
    ProductImage:
      title: ProductImage
      type: object
      properties:
        title:
          type:
            - string
            - 'null'
          maxLength: 128
        alternate_text:
          type:
            - string
            - 'null'
          maxLength: 128
        sort_order:
          type: integer
          format: int32
        url_tiny:
          type: string
          maxLength: 512
        url_thumbnail:
          type: string
          maxLength: 512
        url_standard:
          type: string
          maxLength: 512
        url_zoom:
          type: string
          maxLength: 512
        file_id:
          type: string
        file_type:
          description: MIME type of the file, e.g. `image/png`.
          type: string
      x-tags:
        - Catalog
    ProductPackaging:
      title: ProductPackaging
      type:
        - object
        - 'null'
      required:
        - pack_width
        - pack_height
        - pack_length
        - pack_dry_weight
        - units_per_pack
        - vertical_rotation
      properties:
        product_id:
          type: string
          readOnly: true
        product_variant_id:
          description: '`null` when packaging applies to a product without variants.'
          type:
            - string
            - 'null'
          readOnly: true
        product_name:
          type: string
          readOnly: true
        variant_name:
          description: '`null` when packaging applies to a product without variants.'
          type:
            - string
            - 'null'
          readOnly: true
        pack_width:
          type: number
          format: float
        pack_height:
          type: number
          format: float
        pack_length:
          type: number
          format: float
        pack_dry_weight:
          type: number
          format: float
        units_per_pack:
          type: integer
          format: int32
        vertical_rotation:
          description: >-
            Indicates whether items can be rotated during packing or if they
            must be kept in a strictly vertical orientation.
          type: boolean
        shipper_width:
          type:
            - number
            - 'null'
          format: float
        shipper_height:
          type:
            - number
            - 'null'
          format: float
        shipper_length:
          type:
            - number
            - 'null'
          format: float
        shipper_dry_weight:
          type:
            - number
            - 'null'
          format: float
        units_per_shipper:
          type:
            - integer
            - 'null'
          format: int32
      x-tags:
        - Catalog
    ProductPricing:
      title: ProductPricing
      type: object
      required:
        - customer_group_id
        - cost_price
        - listing_price
        - selling_price
        - tax_rate
      properties:
        customer_group_id:
          description: >-
            customer group id. for different pricing model in case of multiple
            customer groups.
          type:
            - string
            - 'null'
        cost_price:
          type:
            - number
            - 'null'
          format: double
        listing_price:
          type: number
          format: double
        selling_price:
          type: number
          format: double
        min_order_quantity:
          type:
            - integer
            - 'null'
          format: int32
          default: 1
          minimum: 1
        max_order_quantity:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 1
        incremental_quantity:
          type:
            - integer
            - 'null'
          format: int32
          default: 1
          minimum: 1
        tax_type:
          type: string
          default: GST
          enum:
            - GST
            - VAT
            - ECO
        tax_rate:
          type: number
          format: double
      x-tags:
        - Catalog
    ProductPromotion:
      title: ProductPromotion
      oneOf:
        - $ref: '#/components/schemas/DiscountBasedPromotion'
        - $ref: '#/components/schemas/FixedPricePromotion'
        - $ref: '#/components/schemas/VolumeBasedPromotion'
        - $ref: '#/components/schemas/VolumeBasedTierPromotion'
        - $ref: '#/components/schemas/FreeGoodsPromotion'
        - type: 'null'
      x-tags:
        - Catalog
    SalesChannel:
      title: SalesChannel
      type: object
      required:
        - id
        - name
        - active
      properties:
        id:
          type: string
        name:
          type: string
          readOnly: true
        kind:
          type: string
          enum:
            - storefront
            - marketplace
        active:
          type: boolean
          readOnly: true
        sales_channel_type:
          description: 'Observed values: `commercengine`, `web`, `pos`.'
          type:
            - string
            - 'null'
          readOnly: true
        sales_channel_slug:
          type:
            - string
            - 'null'
          readOnly: true
    Seo:
      title: Seo
      type: object
      required:
        - title
        - description
        - keywords
      properties:
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        keywords:
          type:
            - array
            - 'null'
    ProductShipping:
      title: ProductShipping
      type: object
      required:
        - handling_charge
      properties:
        handling_charge:
          description: >-
            A handling charge is an additional fee applied to cover the costs
            associated with preparing, packaging, and processing an order for
            shipment or delivery.
          type: number
          minimum: 0
      x-tags:
        - Catalog
    ProductStatus:
      enum:
        - draft
        - active
        - inactive
    ProductSubscription:
      title: ProductSubscription
      type: object
      required:
        - subscription_plan
        - billing_interval
        - billing_frequency
        - billing_limit
        - billing_trial_days
        - fulfill_separately
        - subscription_price
      properties:
        subscription_plan_id:
          type: string
        subscription_plan:
          type: string
        billing_interval:
          type: integer
          format: int32
        billing_frequency:
          type: string
          enum:
            - Weekly
            - Bimonthly
            - Monthly
            - Quarterly
            - Semiannually
            - Annually
        billing_limit:
          type:
            - integer
            - 'null'
        billing_trial_days:
          type: integer
          format: int32
          default: 0
        order_interval:
          type:
            - integer
            - 'null'
        order_frequency:
          type:
            - string
            - 'null'
          enum:
            - Weekly
            - Bimonthly
            - Monthly
            - Quarterly
            - Semiannually
            - Annually
            - null
        order_limit:
          type:
            - integer
            - 'null'
        fulfill_separately:
          type: boolean
        subscription_price:
          type: array
          items:
            type: object
            required:
              - subscription_price
              - minimum_quantity
              - customer_group_id
            properties:
              minimum_quantity:
                type: integer
                default: 1
              customer_group_id:
                description: customer group id.
                type:
                  - string
                  - 'null'
              subscription_price:
                type: number
                format: double
          minItems: 1
        quantity:
          type: integer
          default: 1
      x-tags:
        - Catalog
    ProductType:
      title: ProductType
      description: Type of product
      type: string
      enum:
        - physical
        - digital
        - bundle
      x-tags:
        - Catalog
    SellerBasicDetail:
      title: SellerBasicDetail
      type: object
      properties:
        id:
          type: string
        trade_name:
          type: string
        legal_name:
          type: string
        business_type:
          $ref: '#/components/schemas/SellerBusinessType'
        tax_identification_number:
          type: string
    ColorObject:
      title: ColorObject
      type: object
      required:
        - name
        - hexcode
      properties:
        name:
          type: string
        hexcode:
          type: string
    DiscountBasedPromotion:
      title: DiscountBasedPromotion
      description: promotion_type = discount
      type: object
      required:
        - promotion_type
        - starts_at
        - details
      properties:
        id:
          type: string
          readOnly: true
        promotion_type:
          enum:
            - discount
        starts_at:
          type: string
        expires_at:
          description: null means never expires.
          type:
            - string
            - 'null'
        details:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/PercentageBasedDiscount'
              - $ref: '#/components/schemas/FixedAmountBasedDiscount'
    FixedPricePromotion:
      title: FixedPricePromotion
      description: promotion_type = fixed-price
      type: object
      required:
        - promotion_type
        - starts_at
        - details
      properties:
        id:
          type: string
          readOnly: true
        promotion_type:
          enum:
            - fixed-price
        starts_at:
          type: string
        expires_at:
          description: null means never expires.
          type:
            - string
            - 'null'
        details:
          type: array
          items:
            type: object
            required:
              - offer_price
              - customer_group_id
              - minimum_quantity
              - maximum_quantity
            properties:
              offer_price:
                type: number
              customer_group_id:
                type:
                  - string
                  - 'null'
              minimum_quantity:
                description: >-
                  It refers to the minimum quantity of a specific item a
                  customer must purchase to qualify for the promotion.
                type: integer
                default: 1
              maximum_quantity:
                description: >-
                  It refers to the maximum quantity of a specific item a
                  customer can purchase in order to qualify for the promotion.
                  If this field is set to null, it indicates that there is no
                  limit.
                type:
                  - integer
                  - 'null'
    VolumeBasedPromotion:
      title: VolumeBasedPromotion
      description: promotion_type = volume-based
      type: object
      required:
        - promotion_type
        - starts_at
        - details
      properties:
        id:
          type: string
          readOnly: true
        promotion_type:
          enum:
            - volume-based
        starts_at:
          type: string
        expires_at:
          description: null means never expires.
          type:
            - string
            - 'null'
        details:
          type: array
          items:
            type: object
            required:
              - customer_group_id
              - slabs
            properties:
              customer_group_id:
                type:
                  - string
                  - 'null'
              slabs:
                type: array
                items:
                  type: object
                  required:
                    - quantity
                    - quantity_condition
                    - discount_percent
                  properties:
                    quantity:
                      type: integer
                    quantity_condition:
                      description: >-
                        `less-or-equal` and `less` make the tier "up to"
                        `quantity`; `greater-or-equal` and `greater` make it
                        "from" `quantity`. A line gets the highest "from" tier
                        its quantity reaches; below the first, the "up to" tier
                        that covers it; otherwise the product's price. A
                        promotion has at most one "up to" tier, ending below its
                        first "from" tier, and no two tiers starting from the
                        same quantity.
                      enum:
                        - less
                        - less-or-equal
                        - greater
                        - greater-or-equal
                    discount_percent:
                      type: number
                      maximum: 100
                      minimum: 0
    VolumeBasedTierPromotion:
      title: VolumeBasedTierPromotion
      description: >-
        promotion_type = volume-based-tier: per customer group, the unit price
        (`rate`) of each quantity tier. Tiers that would put a quantity in two
        tiers are refused with 400.
      type: object
      required:
        - promotion_type
        - starts_at
        - details
      properties:
        id:
          type: string
          readOnly: true
        promotion_type:
          enum:
            - volume-based-tier
        starts_at:
          type: string
        expires_at:
          description: null means never expires.
          type:
            - string
            - 'null'
        details:
          type: array
          items:
            type: object
            required:
              - customer_group_id
              - slabs
            properties:
              customer_group_id:
                type:
                  - string
                  - 'null'
              slabs:
                type: array
                items:
                  type: object
                  required:
                    - quantity
                    - quantity_condition
                    - rate
                  properties:
                    quantity:
                      type: integer
                    quantity_condition:
                      description: >-
                        `less-or-equal` and `less` make the tier "up to"
                        `quantity`; `greater-or-equal` and `greater` make it
                        "from" `quantity`. A line gets the highest "from" tier
                        its quantity reaches; below the first, the "up to" tier
                        that covers it; otherwise the product's price. A
                        promotion has at most one "up to" tier, ending below its
                        first "from" tier, and no two tiers starting from the
                        same quantity.
                      enum:
                        - less
                        - less-or-equal
                        - greater
                        - greater-or-equal
                    rate:
                      description: >-
                        The unit price of a line in this tier. Applies when
                        lower than the product's price.
                      type: number
                      minimum: 0.01
    FreeGoodsPromotion:
      title: FreeGoodsPromotion
      description: promotion_type = free-goods
      type: object
      required:
        - promotion_type
        - starts_at
        - details
      properties:
        id:
          type: string
          readOnly: true
        promotion_type:
          enum:
            - free-goods
        starts_at:
          type: string
          format: date-time
        expires_at:
          description: null means never expires.
          type:
            - string
            - 'null'
          format: date-time
        details:
          type: array
          items:
            allOf:
              - required:
                  - customer_group_id
                properties:
                  customer_group_id:
                    type:
                      - string
                      - 'null'
              - oneOf:
                  - title: ScaleAutomatically
                    required:
                      - auto_scale
                      - slab
                    properties:
                      auto_scale:
                        description: >-
                          The **auto_scale** key determines whether the
                          promotion should be automatically adjusted based on
                          the ratio between the quantities bought and the
                          quantities received.\n\nIf **true**: The promotion
                          will be applied dynamically according to the ratio of
                          the buy quantity to the get quantity. For example, if
                          the promotion is \"Buy 2, Get 1\" and the customer
                          buys 4 items, they would receive 2 free items (scaling
                          based on the original ratio).\n\nIf **false**: The
                          promotion will be applied strictly according to the
                          predefined conditions. For example, even if the
                          customer buys more items, they will receive the fixed
                          free quantity as defined in the original promotion
                          (e.g., buying 4 would still only get them 1 free
                          item).
                        type: boolean
                      slab:
                        type: object
                        properties:
                          buy_quantity:
                            type: integer
                          get_quantity:
                            type: integer
                          quantity_condition:
                            description: >-
                              Defines how the system will evaluate the
                              buy_quantity to determine if the promotion should
                              be applied.
                            enum:
                              - less
                              - less-or-equal
                              - greater
                              - greater-or-equal
                        required:
                          - buy_quantity
                          - get_quantity
                          - quantity_condition
                  - title: CustomSlabs
                    required:
                      - slabs
                    properties:
                      slabs:
                        type: array
                        items:
                          type: object
                          properties:
                            buy_quantity:
                              type: integer
                            get_quantity:
                              type: integer
                            quantity_condition:
                              description: >-
                                Defines how the system will evaluate the
                                buy_quantity to determine if the promotion
                                should be applied.
                              enum:
                                - less
                                - less-or-equal
                                - greater
                                - greater-or-equal
                          required:
                            - buy_quantity
                            - get_quantity
                            - quantity_condition
            type: object
    SellerBusinessType:
      title: SellerBusinessType
      type: string
      enum:
        - sole_proprietorship
        - private_limited
        - public_listed
        - public_limited
        - state_owned
        - charity
        - individual
    PercentageBasedDiscount:
      title: PercentageBasedDiscount
      description: promotion_type = discount
      type:
        - object
        - 'null'
      required:
        - discount_type
        - discount_percent
        - customer_group_id
        - minimum_quantity
        - maximum_quantity
        - maximum_discount_amount
      properties:
        discount_type:
          type: string
          const: percentage
        discount_percent:
          type: number
          maximum: 100
          minimum: 0
        customer_group_id:
          type:
            - string
            - 'null'
        minimum_quantity:
          description: >-
            It refers to the minimum quantity of a specific item a customer must
            purchase to qualify for the promotion.
          type: integer
          default: 1
        maximum_quantity:
          description: >-
            It refers to the maximum quantity of a specific item a customer can
            purchase in order to qualify for the promotion. If this field is set
            to null, it indicates that there is no limit.
          type:
            - integer
            - 'null'
        maximum_discount_amount:
          description: >-
            When a value is specified, the discount amount will not exceed the
            defined maximum, ensuring that the promotion stays within a
            controlled discount range. If this field is set to null, it
            indicates that there is no limit to the discount amount.
          type:
            - number
            - 'null'
    FixedAmountBasedDiscount:
      title: FixedAmountBasedDiscount
      description: promotion_type = discount
      type:
        - object
        - 'null'
      required:
        - discount_type
        - discount_fixed_amount
        - customer_group_id
        - minimum_quantity
        - maximum_quantity
      properties:
        discount_type:
          type: string
          const: fixed-amount
        discount_fixed_amount:
          type: integer
        customer_group_id:
          type:
            - string
            - 'null'
        minimum_quantity:
          description: >-
            It refers to the minimum quantity of a specific item a customer must
            purchase to qualify for the promotion.
          type: integer
          default: 1
        maximum_quantity:
          description: >-
            It refers to the maximum quantity of a specific item a customer can
            purchase in order to qualify for the promotion. If this field is set
            to null, it indicates that there is no limit.
          type:
            - integer
            - 'null'
  responses:
    BadRequest:
      description: The request is invalid or cannot be completed in the current state.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              errors:
                description: Validation details as a field map, a bulk list or a string.
                anyOf:
                  - type: object
                    additionalProperties: true
                  - type: array
                  - type: string
              content:
                type: object
                additionalProperties: true
              details:
                type: string
    Unauthorized:
      description: >-
        The token is missing, invalid or expired, or does not grant access to
        this store and operation.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              details:
                type: string
    InternalServerError:
      description: >-
        The request could not be completed. Quote error_id, when present, when
        contacting support.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
            properties:
              message:
                type: string
              success:
                type: boolean
              code:
                type: string
              details:
                type: string
              error_id:
                type: string
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: >-
        Sign in to the admin dashboard and use the resulting ID token for a
        store and operation you can access. The authenticated dashboard cookie
        is accepted when the Authorization header is absent. Missing or
        insufficient access returns 401.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.