Products API — create and retrieve catalog items

API reference for Alphabet product endpoints: create a new catalog product and retrieve it by ID. Create requires CatalogWrite policy.

The products API provides basic catalog management — creating new products and retrieving them by ID. Creating a product requires the CatalogWrite authorization policy; retrieving a product is open to anonymous requests.

Create a product

POST /api/v1/products

Creates a new catalog product, persists it, and returns the created representation. The response Location header points to the URL of the new resource.

Authorization: CatalogWrite policy required.

Request body

name · string · required

Display name of the product. Must be non-empty.

description · string

Optional description of the product.

price · decimal · required

Unit price of the product. Must be a positive value.

currency · string · required

ISO 4217 currency code (e.g. USD, EUR, GBP).

Response

201 Created — returns ProductResponseDto. The Location header is set to /api/v1/products/{id}.

id · guid

Unique identifier for the created product.

name · string

Display name of the product.

description · string

Description of the product.

price · decimal

Unit price of the product.

currency · string

Currency code for the price.

400 Bad Request — returns ProblemDetails when validation fails or the product could not be created.

Example

curl -X POST "https://api.example.com/api/v1/products" \
  -H "Authorization: Bearer <catalog-write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Keyboard",
    "description": "Compact wireless keyboard with USB receiver.",
    "price": 49.99,
    "currency": "USD"
  }'

Example response

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "name": "Wireless Keyboard",
  "description": "Compact wireless keyboard with USB receiver.",
  "price": 49.99,
  "currency": "USD"
}

---

Get a product by ID

GET /api/v1/products/{id}

Returns the product details for the specified ID. This endpoint allows anonymous access — no authentication token is required.

Path parameters

id · guid · required

The unique identifier of the product to retrieve.

Response

200 OK — returns ProductResponseDto.

id · guid

Unique identifier of the product.

name · string

Display name of the product.

description · string

Description of the product.

price · decimal

Unit price of the product.

currency · string

Currency code for the price.

404 Not Found — returns ProblemDetails when no product with the specified ID exists.

Example

curl -X GET "https://api.example.com/api/v1/products/a1b2c3d4-0000-4000-8000-000000000001"

Example response

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "name": "Wireless Keyboard",
  "description": "Compact wireless keyboard with USB receiver.",
  "price": 49.99,
  "currency": "USD"
}