Support Form: Shop API

Support Form for Sylius - Shop API for headless clients: endpoints for extra fields, subject choices and submitting, POST body, curl examples, admin endpoints and error format

Deutsche Version

Back to overview

Support Form: Shop API

Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net

Headless clients use the Shop API instead of the form at /support. Both paths share the same processing. The API validates the answers to your extra fields with the rules of the storefront form, so required fields, lengths, e-mail format and allowed select options are identical. The paths below are relative to the API prefix of your Sylius installation, which is /api/v2 in Sylius.

Endpoints

Method	Path	Description
GET	`/shop/support-form-fields`	Public: the extra fields, sorted by position
GET	`/shop/support-form-fields/{id}`	Public: one extra field
GET	`/shop/support-form-subject-choices`	Public: the subject choices of the current channel as a list of `value` and `label`
POST	`/shop/support-requests`	Public: submit a request
GET	`/admin/support-requests`	Admin: all requests, newest first
GET	`/admin/support-requests/{id}`	Admin: one request

The admin endpoints require ROLE_API_ACCESS, the same permission as any other Sylius admin API resource. There is deliberately no public list of requests because they contain personal data. Creating, changing and deleting fields or configurations is not possible through the API, only in the admin.

POST body

Field	Type	Required	Description
`subject`	String	Yes	The subject. If the channel has a select list, it must be one of the `value` entries from `/shop/support-form-subject-choices`. Without a select list any text is allowed.
`consent`	Boolean	Yes	Must be `true`
`answers`	Object	No	Answers to the extra fields, keyed by the ID of the field, for example `{"12": "jane@example.com"}`

The server sets channel, time, e-mail address and the stored answers. It derives the address of the request from the first answered value of a field of type E-mail, just like in the form.

Checkbox fields only accept real JSON values true or false. Values such as "0", 0 or "false" are rejected by the API.

Examples

Fetch the subject choices of the channel:

curl -s "https://shop.example.com/api/v2/shop/support-form-subject-choices" \
  -H "Accept: application/ld+json"

The response is empty if the channel has no configuration or the active list is empty. In that case a free text is allowed as the subject.

Fetch the extra fields to build the form in your frontend:

curl -s "https://shop.example.com/api/v2/shop/support-form-fields" \
  -H "Accept: application/ld+json"

Submit a request:

curl -s -X POST "https://shop.example.com/api/v2/shop/support-requests" \
  -H "Content-Type: application/ld+json" \
  -H "Accept: application/ld+json" \
  -d '{"subject": "Order arrived damaged", "consent": true, "answers": {"12": "jane@example.com"}}'

The API answers a valid request with 201. The response contains id, createdAt, email and subject.

Error format

The standard error format of API Platform applies. For validation errors the response contains a violations list with propertyPath, message and code. Errors in an answer to an extra field have the path answers[<ID>]. An ID that belongs to no field reports "This field does not exist."

Status	Cause
201	Request stored
400	Wrong data type for `answers`, for example a string instead of an object. On API Platform 4 this also applies to `consent`.
422	`subject` is missing or empty, `consent` is missing or not `true`, the subject is not in the select list, an answer violates the rules of its field, or an extension rejected the request. On API Platform 5 this also applies to a wrong data type for `consent`.
401 / 403	Admin endpoints only: token is missing or lacks `ROLE_API_ACCESS`

The status code for a wrong data type of consent depends on the API Platform version: 400 on API Platform 4, 422 on API Platform 5. All other status codes are identical on both versions.

If an extension rejects the request through the PRE_PERSIST event (see Extensibility), the API answers with 422. The response carries the rejection reason of the extension as the message, or the text "Submission rejected." if there is no reason.