API reference

This long page shows how a reference is structured. The table of contents is on the right, and every endpoint has a fixed anchor that can be shared as a link (e.g. api-referenz#store-get-notice).

Base URLs

API	Base URL	Authentication
Store API	/store-api	sw-access-key header
Admin API	/api	OAuth 2 bearer token

Store API

Load the notice of a product

GET /store-api/gb-notice/{productId}

Returns the currently valid notice of a product. If no notice is valid, the route responds with 204 No Content.

Path parameters

Name	Type	Required	Description
productId	UUID	✓	Product ID

Response 200 OK

{
  "apiAlias": "gb_notice",
  "id": "0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
  "text": "Shipping within Germany only.",
  "position": "below_price",
  "validFrom": null,
  "validUntil": "2026-12-24T23:59:59+00:00"
}

Errors

Status	Code	Meaning
400	GB_NOTICE__INVALID_ID	productId is not a valid UUID
404	CONTENT__PRODUCT_NOT_FOUND	Product does not exist or is not visible

Load notices of several products

POST /store-api/gb-notice/list

Request body

Field	Type	Required	Description
productIds	UUID[]	✓	At most 100 IDs
includeExpired	bool		Also return expired notices (default false)

Example request

{
  "productIds": ["0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4", "0190b2c3d4e5f6a7b8c9d0e1f2a3b4c5"]
}

Example response

{
  "elements": {
    "0190a1b2c3d4e5f6a7b8c9d0e1f2a3b4": { "text": "Shipping within Germany only." }
  }
}

note

Products without a valid notice are missing from elements rather than appearing as null.

Admin API

The gb_notice entity is available through the generic Admin API. The usual Shopware routes apply.

Search notices

POST /api/search/gb-notice

Active notices only, newest first

{
  "filter": [{ "type": "equals", "field": "active", "value": true }],
  "sort": [{ "field": "createdAt", "order": "DESC" }],
  "limit": 25
}

Create a notice

POST /api/gb-notice

Field	Type	Required	Description
text	string (translatable)	✓	At most 255 characters
position	enum		below_price, below_buy_button, description
validFrom	datetime		Start of validity
validUntil	datetime		End of validity

Update a notice

PATCH /api/gb-notice/{id}

Only send changed fields. Translations via translations:

{
  "translations": {
    "en-GB": { "text": "Shipping within Germany only." }
  }
}

Delete a notice

DELETE /api/gb-notice/{id}

danger

Deleting also removes all assignments to products and categories. There is no recycle bin.

Events

Event	When	Use
GbNoticeLoadedEvent	After a notice is loaded	Adjust text or position
GbNoticeCriteriaEvent	Before the database query	Add custom filters
gb_notice.written	After saving (DAL)	Invalidate caches

GbNoticeLoadedEvent

public function onNoticeLoaded(GbNoticeLoadedEvent $event): void
{
    $notice = $event->getNotice();
    $notice->setText(mb_strtoupper($notice->getText()));
}

GbNoticeCriteriaEvent

public function onNoticeCriteria(GbNoticeCriteriaEvent $event): void
{
    $event->getCriteria()->addFilter(new EqualsFilter('salesChannelId', $event->getSalesChannelId()));
}

Error codes

Code	HTTP	Description
GB_NOTICE__INVALID_ID	400	Invalid UUID
GB_NOTICE__TOO_MANY_IDS	400	More than 100 IDs requested
GB_NOTICE__TEXT_TOO_LONG	400	Text longer than 255 characters
GB_NOTICE__NOT_FOUND	404	Notice does not exist

Compatibility

Plugin	Shopware	PHP
1.0	6.6.x	8.2 – 8.3

See also Data model and Links.