Product Custom Inputs: Shop API
Shop API of Product Custom Inputs for headless clients: endpoints for fields and order item values, POST body, curl examples, access rules and error format.
Product Custom Inputs: Shop API
This documentation always describes the latest published version.
Headless clients use the Shop API. This is a separate write path: a real add-to-cart request neither goes through CartItemType nor triggers sylius.cart_item_add, so the storefront's form logic never runs there. The paths below are relative to the API prefix of your Sylius installation.
Endpoints
Field definitions
| Method | Path | Description |
|---|---|---|
| GET | /shop/product-custom-input-fields |
Public, sorted by position, filter ?products=<IRI or ID> |
| GET | /shop/product-custom-input-fields/{id} |
One field |
| GET | /admin/product-custom-input-fields |
Admin, read-only |
| GET | /admin/product-custom-input-fields/{id} |
Admin, one field |
| DELETE | /admin/product-custom-input-fields/{id} |
Admin, delete a field |
Creating and changing fields is not possible through the API. That works in the admin only.
Values on order items
| Method | Path | Description |
|---|---|---|
| GET | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs |
All values of the item |
| GET | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs/{id} |
One value |
| POST | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs |
Set or overwrite a value |
| GET | /admin/order-item-custom-input-values |
Admin, filterable by orderItem |
| GET | /admin/order-item-custom-input-values/{id} |
Admin, one value |
The admin endpoints require admin authentication with ROLE_API_ACCESS.
POST body
| Field | Type | Required | Description |
|---|---|---|---|
field |
IRI | Yes | The custom input field, e.g. /api/v2/shop/product-custom-input-fields/3 |
value |
String | No | The value in text format (see Configuration) |
The order item comes from the path and cannot be set in the body.
Example
Fetch the fields of a product:
curl -s "https://shop.example.com/api/v2/shop/product-custom-input-fields?products=/api/v2/shop/products/PLUGIN_X" \
-H "Accept: application/ld+json"
Set a value for an item:
curl -s -X POST "https://shop.example.com/api/v2/shop/orders/TOKEN123/items/42/custom-inputs" \
-H "Content-Type: application/ld+json" \
-H "Accept: application/ld+json" \
-d '{"field": "/api/v2/shop/product-custom-input-fields/3", "value": "Anna"}'
Another POST for the same field on the same item overwrites the previous value.
Access and errors
Only the owner of the order has access: a signed-in customer for their own orders, an anonymous visitor only for a guest order. Everything else gets a 404. Writes are only accepted while the order is still a cart.
| Status | Cause |
|---|---|
| 404 | Plugin disabled in the admin ("Enabled" switch), order or item not found or not accessible, order is no longer a cart, field does not belong to the item's product |
| 422 | field missing, or the value violates the field type's rules (required, length, range, format, select, disabled day) |
Concurrent POSTs for the same field on the same item are not guarded. If two requests arrive at the same time, the second can fail on the unique constraint and respond with a server error.