REST API Reference
CarphaCom exposes three API surfaces. All endpoints return JSON.
Conventions
- Base URL:
https://shop.example.com - Content-Type:
application/json - Errors:
4xx/5xxwith{ "type": "...", "message": "..." }body. - Pagination:
?limit=N&offset=N, response{ items, count, limit, offset }.
Authentication
| Surface | Auth |
|---|---|
| /admin/* | Bearer JWT (POST /auth/user/emailpass to obtain) |
| /store/* | Publishable key in x-publishable-api-key header |
| /store/marketplace/* | Public, no auth |
| /auth/* | Public |
Full auth details in Authentication.
Quick endpoint reference
Admin (selected)
| Method | Path | Purpose |
|---|---|---|
| GET | /admin/products | List products |
| POST | /admin/products | Create product |
| GET | /admin/orders | List orders |
| POST | /admin/orders/{id}/fulfillments | Create fulfillment |
| GET | /admin/plugins | List installed plugins |
| POST | /admin/plugins/install | Install a marketplace item |
| DELETE | /admin/plugins/{id} | Uninstall a plugin |
| GET | /admin/plugins/check-updates | Check for marketplace updates |
| GET | /admin/notifications | List notifications |
Store (selected)
| Method | Path | Purpose |
|---|---|---|
| GET | /store/products | List products |
| POST | /store/carts | Create cart |
| POST | /store/carts/{id}/line-items | Add to cart |
| POST | /store/carts/{id}/complete | Place order |
| GET | /store/regions | List regions |
| POST | /store/customers | Register customer |
Federation (marketplace API on carphacom.com)
| Method | Path | Purpose |
|---|---|---|
| GET | /store/marketplace/feed | Catalog of available items |
| GET | /store/marketplace/updates?versions={...} | Update check |
| GET | /store/marketplace/download/{id}/{version} | Signed download URL |
| POST | /store/marketplace/checkout/session | Start a paid install checkout |
| POST | /store/marketplace/license/verify | Verify a license key |
Examples
Create a product
curl -X POST https://shop.example.com/admin/products \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Hand-knit scarf",
"handle": "hand-knit-scarf",
"description": "100% merino wool.",
"variants": [{
"title": "Default",
"prices": [{ "currency_code": "ron", "amount": 24900 }],
"manage_inventory": true,
"inventory_quantity": 50
}]
}'
Install a marketplace plugin
curl -X POST https://shop.example.com/admin/plugins/install \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"marketplace_id": "@carphacom/seo-essentials",
"version": "1.0.0",
"license_key": null
}'
For full per-endpoint docs, see Admin Endpoints and Store Endpoints.