@86d-app/instagram-shop

The Modern Foundation for Commerce

X · LinkedIn

This project is under active development and is not ready for production use.

Instagram Shop Module

Documentation: 86d.app/docs/modules/instagram-shop

Instagram Shopping integration for product listings, Instagram media product tagging, catalog synchronization, and order management.

Installation

npm install @86d-app/instagram-shop

Usage

import instagramShop from "@86d-app/instagram-shop";

const module = instagramShop({
  accessToken: "your-access-token",
  businessId: "your-business-id",
  catalogId: "your-catalog-id",
});

Configuration

Option	Type	Default	Description
accessToken	string	-	Instagram API access token
businessId	string	-	Instagram Business account ID
catalogId	string	-	Instagram catalog ID

Store Endpoints

Method	Path	Description
POST	/instagram-shop/webhooks	Receive Instagram webhook notifications

Admin Endpoints

Method	Path	Description
POST	/admin/instagram-shop/listings/create	Create a new listing
GET	/admin/instagram-shop/listings	List all listings
GET	/admin/instagram-shop/listings/:id	Get listing by ID
POST	/admin/instagram-shop/listings/:id/update	Update a listing
POST	/admin/instagram-shop/listings/:id/delete	Delete a listing
POST	/admin/instagram-shop/listings/:id/tag	Tag a product in an Instagram post
POST	/admin/instagram-shop/listings/:id/untag	Remove a product tag from a post
POST	/admin/instagram-shop/sync	Trigger catalog sync
GET	/admin/instagram-shop/syncs	List catalog sync history
GET	/admin/instagram-shop/orders	List all orders
GET	/admin/instagram-shop/orders/:id	Get order by ID
POST	/admin/instagram-shop/orders/:id/status	Update order status
GET	/admin/instagram-shop/stats	Get channel statistics

Controller API

interface InstagramShopController extends ModuleController {
  createListing(params: { localProductId: string; title: string; externalProductId?: string; status?: ListingStatus; syncStatus?: SyncStatus; metadata?: Record<string, unknown> }): Promise<Listing>;
  updateListing(id: string, params: Partial<Listing>): Promise<Listing | null>;
  deleteListing(id: string): Promise<boolean>;
  getListing(id: string): Promise<Listing | null>;
  getListingByProduct(localProductId: string): Promise<Listing | null>;
  listListings(params?: { status?: ListingStatus; syncStatus?: SyncStatus; take?: number; skip?: number }): Promise<Listing[]>;
  tagProduct(listingId: string, mediaId: string): Promise<Listing | null>;
  untagProduct(listingId: string, mediaId: string): Promise<Listing | null>;
  getProductTags(listingId: string): Promise<string[]>;
  syncCatalog(): Promise<CatalogSync>;
  getLastSync(): Promise<CatalogSync | null>;
  listSyncs(params?: { take?: number; skip?: number }): Promise<CatalogSync[]>;
  receiveOrder(params: { externalOrderId: string; instagramOrderId: string; igUsername?: string; items: unknown[]; subtotal: number; shippingFee: number; platformFee: number; total: number; ... }): Promise<ChannelOrder>;
  getOrder(id: string): Promise<ChannelOrder | null>;
  updateOrderStatus(id: string, status: OrderStatus, trackingNumber?: string, trackingUrl?: string): Promise<ChannelOrder | null>;
  listOrders(params?: { status?: OrderStatus; take?: number; skip?: number }): Promise<ChannelOrder[]>;
  getChannelStats(): Promise<ChannelStats>;
}

Types

type ListingStatus = "draft" | "pending" | "active" | "rejected" | "suspended";
type SyncStatus = "pending" | "synced" | "failed" | "outdated";
type OrderStatus = "pending" | "confirmed" | "shipped" | "delivered" | "cancelled" | "refunded";
type CatalogSyncStatus = "pending" | "syncing" | "synced" | "failed";

Notes

• Product tagging (tagProduct/untagProduct) links products to Instagram media posts and stories via media IDs.
• Each listing tracks an instagramMediaIds array of tagged media.
• Orders include Instagram-specific fields: instagramOrderId and igUsername.
• Similar architecture to the facebook-shop module, with added media tagging capabilities.
• Revenue calculations in stats exclude cancelled and refunded orders.
• Catalog sync creates a tracking record; connect to Instagram Graph API for actual synchronization.