## How it works

Use the shop catalog to calculate prices server-side and retain product lines on payments. Product data, prices and optional add-ons form one consistent basis for checkout, refunds and invoices.

## Implementation

Select the shop for catalog requests. One-time products create payments; recurring products create subscriptions; add-ons extend a purchase; bundles group one-time products. Choose a price and quantity from the catalog rather than trusting a browser-submitted total. Product images must be publicly reachable. Publishing a catalog entry does not automatically synchronize it to a processor: use the explicit catalog sync where supported.

## Create a product

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `name` | string | Yes | Shown in checkout and on invoices. |
| `kind` | string | Yes | See below. |
| `prices` | array | Yes, except `sum` bundles | `amount`, `currency`, `is_default`, `nickname`. Default: the first price. |
| `product_id` | string | No | 1–64 letters, digits, `-`, `_`. Default: generated `prd_…`. Never changes. |
| `description`, `image_url`, `metadata` | | No | Display and your data. |
| `aliases` | array | No | Up to 20 other names `products[].product` accepts. |

## Create a product

| `kind` | Sold through |
| --- | --- |
| `one_time` | A payment. |
| `recurring` | A [subscription](/docs/payment-api/subscriptions/). |
| `addon` | A payment, as an extra to a `one_time` product. |
| `bundle` | A payment, as one offer of several `one_time` products. |

## Related guides

- [Subscriptions](/docs/payment-api/subscriptions/)
- [Refunds](/docs/payment-api/refunds/)

## Request examples

```bash
curl -X POST https://api.spicepay.net/products \
  -H 'api-key: YOUR_API_KEY' \
  -H 'X-Profile-Id: pro_xxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "coffee-1kg",
    "name": "Coffee beans",
    "description": "1 kg bag",
    "kind": "one_time",
    "prices": [
      { "amount": 1999, "currency": "EUR", "is_default": true }
    ]
  }'
```

```bash
curl -X POST https://api.spicepay.net/payments \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "coffee-1kg",
    "profile_id": "pro_xxxxx",
    "payment_link": true,
    "return_url": "https://shop.example/return"
  }'
```

```bash
curl -X POST https://api.spicepay.net/payments \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile_id": "pro_xxxxx",
    "products": [
      { "product": "coffee-1kg", "quantity": 2 },
      { "product": "gift-wrap" }
    ],
    "payment_link": true,
    "return_url": "https://shop.example/return"
  }'
```