Petpooja Stores API

openapi: 3.0.1
info:
  title: Petpooja Online Ordering API
  description: >-
    The Petpooja Online Ordering API (V2.1.0) lets partner ordering platforms and
    aggregators integrate with the Petpooja restaurant POS. Documented capabilities
    include fetching a mapped restaurant's menu/catalog, pushing online orders into
    the POS (save_order), receiving order-status updates on a partner callback_url,
    receiving full menu payloads via a partner Push Menu endpoint, and reflecting
    item stock and store availability. Authentication uses an app key, app secret,
    and access token issued by Petpooja, scoped to a restaurant (restID).


    Some endpoint paths for item stock toggling and store on/off are referenced in
    Petpooja's integration material but are not fully published; where the exact
    path or schema is not publicly reconciled this specification documents the
    behavior and marks it accordingly rather than fabricating details.
  termsOfService: https://www.petpooja.com
  contact:
    name: Petpooja Support
    email: support@petpooja.com
    url: https://www.petpooja.com
  version: 2.1.0
servers:
  - url: https://qle1yy2ydc.execute-api.ap-southeast-1.amazonaws.com/V1
    description: Petpooja menu / restaurant API (AWS API Gateway, ap-southeast-1)
  - url: https://47pfzh5sf2.execute-api.ap-southeast-1.amazonaws.com/V1
    description: Petpooja order API (AWS API Gateway, ap-southeast-1)
security:
  - PetpoojaAuthHeaders: []
tags:
  - name: Menu
    description: Fetch a mapped restaurant's menu / catalog from Petpooja.
  - name: Orders
    description: Push online orders into the Petpooja POS.
  - name: Stores
    description: Store / restaurant online-ordering availability.
  - name: Stock
    description: Item stock and availability.
  - name: Callbacks
    description: Partner-hosted endpoints that Petpooja calls.
paths:
  /mapped_restaurant_menus:
    post:
      operationId: fetchMappedRestaurantMenu
      tags:
        - Menu
      summary: Fetch a mapped restaurant's menu / catalog.
      description: >-
        Returns the full catalog for a mapped restaurant: restaurant details,
        order types, categories and parent categories, items, variations, add-on
        groups, attributes, taxes, and discounts. Authenticated with the app-key,
        app-secret, and access-token headers and scoped by restID.
      security:
        - PetpoojaAuthHeaders: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchMenuRequest'
      responses:
        '200':
          description: Menu payload for the mapped restaurant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
  /save_order:
    servers:
      - url: https://47pfzh5sf2.execute-api.ap-southeast-1.amazonaws.com/V1
    post:
      operationId: saveOrder
      tags:
        - Orders
      summary: Push a new order into the Petpooja POS.
      description: >-
        Submits a new online order to the Petpooja POS. The request carries
        app_key, app_secret, and access_token in the body alongside an orderinfo
        object describing the restaurant, customer, order, order items, taxes, and
        discounts. The order may include a callback_url to which Petpooja posts
        subsequent order-status updates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveOrderRequest'
      responses:
        '200':
          description: Order accepted by the Petpooja POS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SaveOrderResponse'
  /update_store_status:
    post:
      operationId: updateStoreStatus
      tags:
        - Stores
      summary: Turn a store's online ordering on or off (availability).
      description: >-
        Toggles a restaurant/store's online ordering availability and optionally
        sets a turn_on_time after which ordering resumes. The exact endpoint path
        and request schema are referenced in Petpooja integration material but are
        not fully published; this operation documents the known turn_on_time
        behavior. Treat the path and schema as unreconciled.
      security:
        - PetpoojaAuthHeaders: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreStatusRequest'
      responses:
        '200':
          description: Store status updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /update_item_stock:
    post:
      operationId: updateItemStock
      tags:
        - Stock
      summary: Mark menu items in stock or out of stock.
      description: >-
        Sets the in_stock flag for one or more menu items so partner platforms
        reflect live availability against Petpooja POS inventory. The exact
        endpoint path and request schema are not fully published; this operation
        documents the known in_stock behavior. Treat the path and schema as
        unreconciled.
      security:
        - PetpoojaAuthHeaders: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemStockRequest'
      responses:
        '200':
          description: Item stock updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
components:
  securitySchemes:
    PetpoojaAuthHeaders:
      type: apiKey
      in: header
      name: access-token
      description: >-
        Petpooja issues an app-key, app-secret, and access-token per integration
        and a restID per mapped restaurant. Menu/restaurant calls send app-key,
        app-secret, and access-token as request headers; the save_order call sends
        app_key, app_secret, and access_token in the request body. Credentials are
        obtained by emailing support@petpooja.com.
  schemas:
    FetchMenuRequest:
      type: object
      required:
        - restID
      properties:
        restID:
          type: string
          description: Petpooja restaurant identifier for the mapped restaurant.
    MenuResponse:
      type: object
      description: Full catalog payload for a mapped restaurant.
      properties:
        success:
          type: string
          description: Success flag returned by Petpooja (e.g., "1").
        message:
          type: string
        restaurants:
          type: array
          items:
            $ref: '#/components/schemas/Restaurant'
        ordertypes:
          type: array
          items:
            type: object
        categories:
          type: array
          items:
            type: object
        parentcategories:
          type: array
          items:
            type: object
        items:
          type: array
          items:
            $ref: '#/components/schemas/MenuItem'
        variations:
          type: array
          items:
            type: object
        addongroups:
          type: array
          items:
            type: object
        attributes:
          type: array
          items:
            type: object
        taxes:
          type: array
          items:
            type: object
        discounts:
          type: array
          items:
            type: object
    Restaurant:
      type: object
      properties:
        restaurantid:
          type: string
        active:
          type: string
        menusharingcode:
          type: string
          description: Menu Sharing Code identifying the restaurant's shared menu.
        currency_html:
          type: string
        country:
          type: string
        city:
          type: string
        minimumorderamount:
          type: string
        minimumdeliverytime:
          type: string
        deliverycharge:
          type: string
        packaging_charge:
          type: string
    MenuItem:
      type: object
      properties:
        itemid:
          type: string
        itemname:
          type: string
        itemcategoryid:
          type: string
        price:
          type: string
        in_stock:
          type: string
          description: Item availability flag (in stock / out of stock).
        itemallowvariation:
          type: string
        variation:
          type: array
          items:
            type: object
        addon:
          type: array
          items:
            type: object
        item_tax:
          type: string
        is_combo:
          type: string
        combo_items:
          type: array
          items:
            type: object
    SaveOrderRequest:
      type: object
      required:
        - app_key
        - app_secret
        - access_token
        - orderinfo
      properties:
        app_key:
          type: string
        app_secret:
          type: string
        access_token:
          type: string
        orderinfo:
          $ref: '#/components/schemas/OrderInfo'
        udid:
          type: string
        device_type:
          type: string
    OrderInfo:
      type: object
      properties:
        OrderInfo:
          type: object
          properties:
            Restaurant:
              $ref: '#/components/schemas/OrderRestaurant'
            Customer:
              $ref: '#/components/schemas/Customer'
            Order:
              $ref: '#/components/schemas/Order'
            OrderItem:
              type: array
              items:
                $ref: '#/components/schemas/OrderItem'
            Tax:
              type: array
              items:
                type: object
            Discount:
              type: array
              items:
                type: object
    OrderRestaurant:
      type: object
      properties:
        details:
          type: object
          properties:
            res_name:
              type: string
            address:
              type: string
            contact_information:
              type: string
            restID:
              type: string
              description: Petpooja restaurant identifier.
    Customer:
      type: object
      properties:
        details:
          type: object
          properties:
            email:
              type: string
            name:
              type: string
            address:
              type: string
            phone:
              type: string
            latitude:
              type: string
            longitude:
              type: string
    Order:
      type: object
      properties:
        details:
          type: object
          properties:
            orderID:
              type: string
            preorder_date:
              type: string
            preorder_time:
              type: string
            service_charge:
              type: string
            delivery_charges:
              type: string
            dc_tax_percentage:
              type: string
            dc_tax_amount:
              type: string
            packing_charges:
              type: string
            pc_tax_percentage:
              type: string
            pc_tax_amount:
              type: string
            order_type:
              type: string
            ondc_bap:
              type: string
            advanced_order:
              type: string
            payment_type:
              type: string
            table_no:
              type: string
            no_of_persons:
              type: string
            discount_total:
              type: string
            tax_total:
              type: string
            total:
              type: string
            description:
              type: string
            created_on:
              type: string
            enable_delivery:
              type: string
            min_prep_time:
              type: string
            callback_url:
              type: string
              description: >-
                Partner URL Petpooja calls with order-status updates
                (Accept / Reject / Food Ready, etc.).
            collect_cash:
              type: string
            otp:
              type: string
            urgent_order:
              type: boolean
            urgent_time:
              type: integer
    OrderItem:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        gst_liability:
          type: string
        item_tax:
          type: array
          items:
            type: object
        item_discount:
          type: string
        price:
          type: string
        final_price:
          type: string
        quantity:
          type: string
        description:
          type: string
        variation_name:
          type: string
        variation_id:
          type: string
        AddonItem:
          type: object
          properties:
            details:
              type: array
              items:
                type: object
    SaveOrderResponse:
      type: object
      properties:
        success:
          type: string
          description: Success flag (e.g., "1").
        message:
          type: string
        restID:
          type: string
        clientOrderID:
          type: string
        orderID:
          type: string
          description: Petpooja-assigned order identifier.
    StoreStatusRequest:
      type: object
      description: >-
        Unreconciled. Documents the known turn_on / turn_off behavior for store
        availability.
      properties:
        restID:
          type: string
        store_status:
          type: string
          description: Desired store status (e.g., "1" on / "0" off).
        turn_on_time:
          type: string
          description: Time after which online ordering resumes.
        reason:
          type: string
    ItemStockRequest:
      type: object
      description: >-
        Unreconciled. Documents the known in_stock toggle behavior for items.
      properties:
        restID:
          type: string
        type:
          type: string
          description: Entity type being toggled (e.g., item).
        inStock:
          type: boolean
          description: Whether the listed entities are in stock.
        itemID:
          type: array
          items:
            type: string
        autoTurnOnTime:
          type: string
    GenericResponse:
      type: object
      properties:
        success:
          type: string
        message:
          type: string