# E-commerce integration

> Paginated JSON product API, change tracking with changedSince, live price/stock check, per-key quota, pricing rules and self-hosted images.

Connect your website, ERP or marketplace tool to the Giyimport product pool. With your API key you receive products as paginated JSON, pull only what changed and verify live price/stock before adding to cart.

## API keys and request limits

### Key management

- What it does: Create, rotate and revoke API keys in the panel.
- How it works: A key is shown exactly once at creation; only its SHA-256 hash is stored.
- Problem solved: A leaked key staying in use unnoticed.
- Technical detail: Header: x-api-key: gyi_… or Authorization: Bearer gyi_… · active key limit per plan.

### Quota

- What it does: Every plan has a 30-day request quota; when exceeded the API returns 429.
- How it works: Requests from all keys on your account are counted together; usage is shown for 24 h / 7 d / 30 d.
- Problem solved: Unexpected cost and uncontrolled consumption.
- Technical detail: Status codes: 401 invalid key · 403 plan required · 429 quota exceeded.

## Endpoints

| Method and path | Returns |
| --- | --- |
| GET /api/v1/products | Paginated products (page, limit ≤ 100, q, category, supplier, changedSince) |
| GET /api/v1/products/{id} | One product: variants, images, attributes, prices |
| GET /api/v1/products/{id}/live | Instant price and stock verification from the source site |
| GET /api/v1/product-groups | Products grouped by model across colours |
| GET /api/v1/suppliers | Sources and active product counts |
| GET /api/v1/feed.xml | All active products in scope (XML) |

## Change tracking (polling) instead of webhooks

### changedSince

- What it does: Returns products changed since your last pull.
- How it works: Store the time of your last successful pull and send it as changedSince next time.
- Problem solved: The cost of pulling the entire catalog every time.
- Technical detail: Filters on product or source record update time; accepts ISO 8601.

### Live verification

- What it does: Verifies the current source price and stock when your customer adds to cart.
- How it works: /live reads the source page instantly; if the price changed it is written to price history and the pool is updated.
- Problem solved: Selling a product whose price changed or that sold out at the supplier.
- Technical detail: Response: price, suggestedPrice, stock, inStock, active, variants[], checkedAt.

## Categories, attributes and pricing rules

### Category and attribute data

- What it does: Each product includes category, full category path and attributes; trial and product-limited plans are scoped by category selection.
- How it works: The source category tree and attributes are stored during crawling and returned with the same names in API and XML.
- Problem solved: No raw data to map onto your own category tree.
- Technical detail: Fields: category, categoryPath, attributes[{name, value}].

### Pricing rules

- What it does: Sale price = cost + margin + shipping fee + fixed amount, then a rounding rule.
- How it works: Rules are defined per source; salePrice/suggestedPrice in API and XML follow them. For marketplace price pushes an extra percentage and fixed amount can be set per store.
- Problem solved: Calculating every price by hand.
- Technical detail: Rounding: to the cent, ending in .90, or rounded to the hundred ending in .99.

### Image sync

- What it does: Product images are downloaded from the source and hosted on Giyimport servers.
- How it works: Image sync fetches missing images in the background; image URLs in API and XML use our own domain.
- Problem solved: Broken images when a source site changes its image URLs.
- Technical detail: Ordered image list; variant-specific images in variant.imageUrl.

## Sample request

```bash
curl -H "x-api-key: gyi_…" \
  "https://api.giyimport.com/api/v1/products?limit=100&page=1&changedSince=2026-11-01T00:00:00Z"
```