> For the complete documentation index, see [llms.txt](https://docs.spurtcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spurtcommerce.com/api-reference/vendor/marketing/banners-and-widgets.md).

# Banners And Widgets

Manage storefront banners and content widgets.

## Retrieve Banner

> Get /api/banner\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Banners\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/banner":{"get":{"operationId":"getApiBanner","summary":"Retrieve Banner","description":"Get /api/banner\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Banners\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter limit."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter offset."},{"name":"keyword","in":"query","required":false,"schema":{"type":"string"},"description":"Query parameter keyword."},{"name":"status","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter status."},{"name":"count","in":"query","required":false,"schema":{"type":"boolean"},"description":"Query parameter count."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"bannerId":{"type":"integer"},"title":{"type":"string"},"image":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```

## Create or process Banner

> Post /api/banner\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Banners\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/banner":{"post":{"operationId":"postApiBanner","summary":"Create or process Banner","description":"Post /api/banner\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Banners\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"bannerId":{"type":"integer"},"title":{"type":"string"},"image":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}},"requestBody":{"required":false,"description":"Sample request body. Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO. Treat this as an illustrative example, not a complete DTO contract.","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"name":{"type":"string"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"link":{"type":"string"},"sortOrder":{"type":"integer"},"status":{"type":"integer"},"image":{"type":"string"}},"additionalProperties":true}}}}}}}}
```

## Retrieve Banner Banner Detail

> Get /api/banner/banner-detail\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Banners\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/banner/banner-detail":{"get":{"operationId":"getApiBannerBannerDetail","summary":"Retrieve Banner Banner Detail","description":"Get /api/banner/banner-detail\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Banners\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"bannerId","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter bannerId."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"bannerId":{"type":"integer"},"title":{"type":"string"},"image":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```

## Update Banner

> Put /api/banner/:id\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Banners\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/banner/{id}":{"put":{"operationId":"putApiBannerId","summary":"Update Banner","description":"Put /api/banner/:id\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Banners\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value for id."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"bannerId":{"type":"integer"},"title":{"type":"string"},"image":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}},"requestBody":{"required":false,"description":"Sample request body. Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO. Treat this as an illustrative example, not a complete DTO contract.","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"name":{"type":"string"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"link":{"type":"string"},"sortOrder":{"type":"integer"},"status":{"type":"integer"},"image":{"type":"string"}},"additionalProperties":true}}}}}}}}
```

## Remove Banner

> Delete /api/banner/:id\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Banners\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* No request body: the resource identifier is supplied in the URL path.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/banner/{id}":{"delete":{"operationId":"deleteApiBannerId","summary":"Remove Banner","description":"Delete /api/banner/:id\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Banners\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** No request body: the resource identifier is supplied in the URL path.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value for id."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```

## Retrieve Widget

> Get /api/vendor-widget\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Widgets\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/vendor-widget":{"get":{"operationId":"getApiVendorWidget","summary":"Retrieve Widget","description":"Get /api/vendor-widget\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Widgets\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter limit."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter offset."},{"name":"keyword","in":"query","required":false,"schema":{"type":"string"},"description":"Query parameter keyword."},{"name":"status","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter status."},{"name":"count","in":"query","required":false,"schema":{"type":"boolean"},"description":"Query parameter count."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"widgetId":{"type":"integer"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```

## Create or process Widget

> Post /api/vendor-widget\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Widgets\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/vendor-widget":{"post":{"operationId":"postApiVendorWidget","summary":"Create or process Widget","description":"Post /api/vendor-widget\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Widgets\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"widgetId":{"type":"integer"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}},"requestBody":{"required":false,"description":"Sample request body. Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO. Treat this as an illustrative example, not a complete DTO contract.","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"name":{"type":"string"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"link":{"type":"string"},"sortOrder":{"type":"integer"},"status":{"type":"integer"},"image":{"type":"string"}},"additionalProperties":true}}}}}}}}
```

## Retrieve Widget Widget Detail

> Get /api/vendor-widget/widget-detail\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Widgets\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/vendor-widget/widget-detail":{"get":{"operationId":"getApiVendorWidgetWidgetDetail","summary":"Retrieve Widget Widget Detail","description":"Get /api/vendor-widget/widget-detail\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Widgets\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"widgetId","in":"query","required":false,"schema":{"type":"integer"},"description":"Query parameter widgetId."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"widgetId":{"type":"integer"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```

## Update Widget

> Put /api/vendor-widget/:id\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Widgets\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/vendor-widget/{id}":{"put":{"operationId":"putApiVendorWidgetId","summary":"Update Widget","description":"Put /api/vendor-widget/:id\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Widgets\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value for id."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"widgetId":{"type":"integer"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"status":{"type":"integer"}},"additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}},"requestBody":{"required":false,"description":"Sample request body. Illustrative body using common Banner/Widget fields; confirm the route-specific request DTO. Treat this as an illustrative example, not a complete DTO contract.","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"name":{"type":"string"},"widgetTitle":{"type":"string"},"widgetSlugName":{"type":"string"},"link":{"type":"string"},"sortOrder":{"type":"integer"},"status":{"type":"integer"},"image":{"type":"string"}},"additionalProperties":true}}}}}}}}
```

## Remove Widget

> Delete /api/vendor-widget/:id\
> \
> \*\*Authentication:\*\* Vendor bearer token required for protected operations; verify exact permission decorator in controller.\
> \
> \*\*Feature area:\*\* Widgets\
> \
> \*\*Implementation source:\*\* \`src/api/vendor/controllers/BannerController.ts\`\
> \
> \*\*Request example provenance:\*\* No request body: the resource identifier is supplied in the URL path.\
> \
> \*\*Response example provenance:\*\* Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\
> \
> \> \*\*Example status: Illustrative.\*\* The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.

```json
{"openapi":"3.0.3","info":{"title":"SpurtCommerce Vendor API","version":"6.0.0"},"tags":[{"name":"Banners and widgets","description":"Manage storefront banners and content widgets."}],"servers":[{"url":"https://api.example.com","description":"Replace with your SpurtCommerce API host. Paths include the /api prefix."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Paste the JWT access token returned by the corresponding login endpoint."}}},"paths":{"/api/vendor-widget/{id}":{"delete":{"operationId":"deleteApiVendorWidgetId","summary":"Remove Widget","description":"Delete /api/vendor-widget/:id\n\n**Authentication:** Vendor bearer token required for protected operations; verify exact permission decorator in controller.\n\n**Feature area:** Widgets\n\n**Implementation source:** `src/api/vendor/controllers/BannerController.ts`\n\n**Request example provenance:** No request body: the resource identifier is supplied in the URL path.\n\n**Response example provenance:** Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.\n\n> **Example status: Illustrative.** The example is included to demonstrate request/response shape in the reference UI; verify the owning controller and request DTO before using it as a contract.","tags":["Banners and widgets"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Value for id."}],"responses":{"200":{"description":"Successful response. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema. Example is illustrative and does not guarantee a stable response contract.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}},"400":{"description":"Error response example. Illustrative response envelope only. This route inventory does not include its route-specific @apiSuccessExample; response fields and messages must be verified in the matching controller/service. The example is intended to show the common response-wrapper style, not to define a guaranteed response schema.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}},"additionalProperties":true}}}}}}}}}
```