Advertisement Module Documentation¶

Overview¶

The Advertisement module manages promotional banners and advertisements displayed on the storefront. It supports multiple locations, ordering, and active/inactive states.

Data Model¶

Advertisement Entity¶

File: backend/src/modules/advertisement/models/advertisement.ts

Field	Type	Required	Default	Description
id	string	Yes	Auto-generated	Primary key
title	string	No	null	Optional title for the advertisement
image_url	string	Yes	-	URL of the advertisement image (required)
link_url	string	No	null	URL to navigate when clicked
location	string	No	"home_slider"	Display location (e.g., home_slider, banner)
display_order	number	No	0	Order for sorting advertisements
is_active	boolean	No	true	Whether the advertisement is currently active
created_at	datetime	Yes	Auto-set	Timestamp when record was created

Service Methods¶

AdvertisementModuleService¶

File: backend/src/modules/advertisement/service.ts

The service extends MedusaService which automatically provides standard CRUD methods: - listAdvertisements(filters, options) - List advertisements with optional filters - createAdvertisement(data) - Create a new advertisement - updateAdvertisement(id, data) - Update an existing advertisement - deleteAdvertisement(id) - Delete an advertisement

Custom Methods¶

listActiveAdvertisements()¶

Returns all active advertisements sorted by display_order.

async listActiveAdvertisements(): Promise<Advertisement[]>

Returns: Array of active advertisements ordered by display_order ascending.

Example:

const ads = await advertisementModuleService.listActiveAdvertisements()
// Returns: [
//   { id: "1", image_url: "...", location: "home_slider", display_order: 0, is_active: true, ... },
//   { id: "2", image_url: "...", location: "home_slider", display_order: 1, is_active: true, ... }
// ]

Usage Examples¶

Creating an Advertisement¶

const ad = await advertisementModuleService.createAdvertisement({
  title: "Summer Sale",
  image_url: "https://example.com/banner.jpg",
  link_url: "https://example.com/sale",
  location: "home_slider",
  display_order: 1,
  is_active: true,
})

Listing All Advertisements¶

const [ads, count] = await advertisementModuleService.listAdvertisements(
  { location: "home_slider" },
  { order: { display_order: "ASC" } }
)

Updating an Advertisement¶

const updated = await advertisementModuleService.updateAdvertisement(adId, {
  is_active: false,
})

Deleting an Advertisement¶

await advertisementModuleService.deleteAdvertisement(adId)

Getting Active Advertisements for Storefront¶

const activeAds = await advertisementModuleService.listActiveAdvertisements()

Module Registration¶

The module is registered in medusa-config.ts:

modules: [
  {
    resolve: "./src/modules/advertisement",
  },
]

Migration¶

Generate and run migrations:

npx medusa db:generate advertisement
npx medusa db:migrate

This creates the advertisement table in PostgreSQL with all defined columns.

API Routes¶

The module is exposed via custom API routes: - GET /store/advertisements - Returns active advertisements - GET /admin/advertisements - List all advertisements (admin) - POST /admin/advertisements - Create advertisement (admin) - PATCH /admin/advertisements/:id - Update advertisement (admin) - DELETE /admin/advertisements/:id - Delete advertisement (admin)

See STORE_ENDPOINTS.md and ADMIN_ENDPOINTS.md for API details.