Orchestra Internal API Mapping

Stores

Store search and discovery with 3-layer architecture: API Gateway -> Storefront Service -> Core Microservices

View Postman Documentation

3-Layer Architecture

API Gateway Public (Internet)
Storefront Service Internal Orchestration
Core Microservices Internal Services

1. Store Search

Search and filter stores based on location, fulfillment type, and business requirements

Search Stores

Multi-Scenario

Search and filter stores with multiple result scopes (1 step)

POST
API Gateway Layer 1 - Public
POST /stores/search
Storefront Service Layer 2 - Orchestration
POST /stores/search

Orchestrates 1 service call

Layer 3 - Service Calls (1 Step)
Request Payload 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777,
    "address_components": {
      "city": "Mumbai",
      "zip_code": "400001",
      "country": "India"
    }
  },
  "filters": {
    "fulfillment_type": ["DELIVERY", "PICKUP"],
    "business_category_id": ["CAT001", "CAT002"],
    "max_distance_km": 10
  },
  "options": {
    "include_default_store": true
  },
  "result": {
    "type": "MULTIPLE",
    "scope": "serviceable-stores"
  },
  "pagination": {
    "page": 1,
    "per_page": 50
  },
  "sorting": {
    "sort_by": "distance",
    "sort_order": "asc"
  }
}
Result Scope Options
all-store

Returns all stores regardless of serviceability

serviceable-stores

Returns stores that can service the user's location

fulfillment-store

Returns the optimal store for order fulfillment

pickup-available-stores

Returns stores where pickup is available

default-store

Returns the tenant's default store

2. Search Scenarios

Different payload configurations for various use cases

1

Get All Stores (Multiple)

Display all available stores regardless of location or serviceability

all-store 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777,
    "address_components": {
      "city": "Mumbai",
      "zip_code": "400001",
      "country": "India"
    }
  },
  "filters": {
    "fulfillment_type": ["DELIVERY", "PICKUP"]
  },
  "result": {
    "type": "MULTIPLE",
    "scope": "all-store"
  },
  "pagination": {
    "page": 1,
    "per_page": 50
  },
  "sorting": {
    "sort_by": "distance",
    "sort_order": "asc"
  }
}
2

Get Fulfillment Store (Single)

Find the optimal store to fulfill an order based on inventory, distance, and business rules

fulfillment-store 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777,
    "address_components": {
      "city": "Mumbai",
      "zip_code": "400001",
      "country": "India"
    }
  },
  "filters": {
    "fulfillment_type": ["DELIVERY"],
    "max_distance_km": 15
  },
  "result": {
    "type": "SINGLE",
    "scope": "fulfillment-store"
  }
}
3

Get Pickup-Available Stores (Multiple)

Show all stores where customers can pick up their orders

pickup-available-stores 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777,
    "address_components": {
      "city": "Mumbai",
      "zip_code": "400001",
      "country": "India"
    }
  },
  "filters": {
    "fulfillment_type": ["PICKUP"],
    "max_distance_km": 20
  },
  "result": {
    "type": "MULTIPLE",
    "scope": "pickup-available-stores"
  },
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "sorting": {
    "sort_by": "distance",
    "sort_order": "asc"
  }
}
4

Get Default Store (Single)

Retrieve the tenant's default/primary store for fallback scenarios

default-store 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777
  },
  "result": {
    "type": "SINGLE",
    "scope": "default-store"
  }
}
5

Get Serviceable Stores (Multiple)

Find all stores that can service the customer's location for delivery

serviceable-stores 
{
  "user_context": {
    "latitude": 19.0760,
    "longitude": 72.8777,
    "address_components": {
      "city": "Mumbai",
      "zip_code": "400001",
      "country": "India"
    }
  },
  "filters": {
    "fulfillment_type": ["DELIVERY"],
    "max_distance_km": 10
  },
  "result": {
    "type": "MULTIPLE",
    "scope": "serviceable-stores"
  },
  "pagination": {
    "page": 1,
    "per_page": 20
  },
  "sorting": {
    "sort_by": "distance",
    "sort_order": "asc"
  }
}

Services Used in Stores Module

🏪

Storefront Service

Orchestration layer for store search operations

🏢

Account Service

Store data, search, and location-based queries

Stores Module - Orchestra Internal API Mapping | 1 API | 5 Scenarios | 1 Total Step