Agent-ready

Shopial Integrator API

Vendors and third-party integrators (ERP, PIM, Yengeç, Sopyo, Entegra) connect via this REST API. No formal hub partnership is required — create your API key in the vendor panel.

OpenAPI YAML llms.txt Create API key →

Authentication

All /api/v1 requests use a Bearer token (vendor API key).

Rate limit: 120 requests per minute (API key + IP). Retry after 429.

Authorization header

Authorization: Bearer shp_your_api_key_here

Scopes

Select at least one scope when creating a key.

PRODUCTS_READ
PRODUCTS_WRITE
INVENTORY_WRITE
ORDERS_READ
WEBHOOKS_MANAGE

Endpoints

JSON bodies; errors use code, message, and details.

Method	Path	Scope
GET	/api/v1/health	—
GET	/api/v1/products	PRODUCTS_READ
POST	/api/v1/products	PRODUCTS_WRITE
POST	/api/v1/products/upsert	PRODUCTS_WRITE
POST	/api/v1/products/bulk	PRODUCTS_WRITE
POST	/api/v1/products/bulk-upsert	PRODUCTS_WRITE
GET	/api/v1/products/lookup	PRODUCTS_READ
GET	/api/v1/products/{id}	PRODUCTS_READ
PATCH	/api/v1/products/{id}	PRODUCTS_WRITE
DELETE	/api/v1/products/{id}	PRODUCTS_WRITE
GET	/api/v1/products/{id}/variants	PRODUCTS_READ
POST	/api/v1/products/{id}/variants	PRODUCTS_WRITE
PATCH	/api/v1/products/{id}/variants/{variantId}	PRODUCTS_WRITE
DELETE	/api/v1/products/{id}/variants/{variantId}	PRODUCTS_WRITE
GET	/api/v1/offers	PRODUCTS_READ
POST	/api/v1/offers	PRODUCTS_WRITE
GET	/api/v1/offers/{id}	PRODUCTS_READ
PATCH	/api/v1/offers/{id}	PRODUCTS_WRITE
DELETE	/api/v1/offers/{id}	PRODUCTS_WRITE
PATCH	/api/v1/inventory/{sku}	INVENTORY_WRITE
GET	/api/v1/orders	ORDERS_READ
GET	/api/v1/orders/{id}	ORDERS_READ
GET	/api/v1/categories	PRODUCTS_READ
GET	/api/v1/webhooks	WEBHOOKS_MANAGE
POST	/api/v1/webhooks	WEBHOOKS_MANAGE
DELETE	/api/v1/webhooks/{id}	WEBHOOKS_MANAGE

Storefront JSON (public)

No API key required; IP + slug rate limits apply. JSON alternative to HTML storefront pages.

Method	Path	Scope
GET	/api/v1/vendors/{slug}	—
GET	/api/v1/vendors/{slug}/products	—

Product sync (bridge / PIM)

Upsert and lookup endpoints for recurring imports from external platforms.

Shopial Bridge or your custom integrator can match products by externalId, sku, or barcode and update in place. The product core is product-scoped, not category-owned; primaryCategoryId is only a placement/template hint. POST /products/bulk only creates; use bulk-upsert for updates.

matchBy: externalId (default), sku, or barcode — the selected field must be present in the payload.
options + variants carry the product graph; metadata.integrator.externalId + metadata.integrator.source are the mapping keys; metadata.schemaOrg and metadata.gs1 hold GS1/schema.org identity fields, while googleMerchant / metaCatalog / ikas / trendyol / hepsiburada / shopify blocks carry channel-specific SEO data.
Variant optionValues use stable request keys: legacy "Option::Value" (e.g. Color::Red) or facet attr::{attributeId}. Responses include variantKey (sorted optionKeys joined with "|") and optionKeys; status ACTIVE | ARCHIVED. Incremental CRUD without a full product payload: GET/POST /products/{id}/variants, PATCH/DELETE /products/{id}/variants/{variantId}. options may include attributeSetId + attributeIds for facet mapping.
imageUrls (max 20) are fetched remotely and stored on S3; replaceImages=true removes existing product images first. Images and variant data are not category-owned.

Sample requests

List products

curl -s "https://www.shopial.com/api/v1/products?page=1&limit=24" \
  -H "Authorization: Bearer shp_your_api_key_here"

Create product

curl -s -X POST "https://www.shopial.com/api/v1/products" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Örnek ürün",
    "price": 199.9,
    "vatRate": 20,
    "inventory": 10,
    "metadata": {
      "schemaOrg": {
        "brand": "Örnek Marka",
        "productType": "Giyim",
        "gtin": "869000000001",
        "mpn": "ORNEK-001"
      },
      "gs1": {
        "gtin13": "869000000001",
        "mpn": "ORNEK-001",
        "brand": "Örnek Marka",
        "productType": "Giyim"
      }
    }
  }'

Upsert product (sync)

curl -s -X POST "https://www.shopial.com/api/v1/products/upsert" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "matchBy": "externalId",
    "externalId": "TY-12345",
    "externalSource": "trendyol",
    "title": "Senkron ürün",
    "price": 299.9,
    "sku": "TY-12345",
    "inventory": 12,
    "primaryCategoryId": "cat_apparel",
    "options": [
      { "title": "Renk", "values": ["Siyah", "Beyaz"] },
      { "title": "Beden", "values": ["M", "L"] }
    ],
    "variants": [
      {
        "sku": "TY-12345-S-M",
        "barcode": "869000000001",
        "price": 299.9,
        "inventory": 5,
        "optionValues": ["Renk::Siyah", "Beden::M"],
        "isDefault": true
      },
      {
        "sku": "TY-12345-W-L",
        "barcode": "869000000002",
        "price": 299.9,
        "inventory": 7,
        "optionValues": ["Renk::Beyaz", "Beden::L"]
      }
    ],
    "imageUrls": ["https://cdn.example.com/img1.jpg"],
    "commerceFeed": {
      "brand": "Örnek Marka",
      "gtin": "869000000001",
      "mpn": "TY-12345",
      "condition": "new",
      "googleProductCategory": "Apparel & Accessories",
      "itemGroupId": "TY-12345",
      "color": "Siyah",
      "size": "M"
    },
    "metadata": {
      "integrator": { "externalId": "TY-12345", "source": "trendyol" },
      "schemaOrg": {
        "brand": "Örnek Marka",
        "productType": "Giyim > Üst Giyim",
        "category": "Giyim",
        "condition": "new",
        "gtin": "869000000001",
        "mpn": "TY-12345",
        "sku": "TY-12345",
        "color": "Siyah",
        "size": "M"
      },
      "gs1": {
        "gtin13": "869000000001",
        "mpn": "TY-12345",
        "sku": "TY-12345",
        "brand": "Örnek Marka",
        "productType": "Giyim > Üst Giyim",
        "category": "Giyim"
      },
      "trendyol": { "productMainId": "TY-12345" }
    }
  }'

Bulk upsert

curl -s -X POST "https://www.shopial.com/api/v1/products/bulk-upsert" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-batch-2026-06-08" \
  -d '{"products":[{"matchBy":"sku","sku":"WP-001","title":"WP ürün","price":149}]}'

Product lookup

curl -s "https://www.shopial.com/api/v1/products/lookup?externalId=TY-12345&externalSource=trendyol" \
  -H "Authorization: Bearer shp_your_api_key_here"

List variants

curl -s "https://www.shopial.com/api/v1/products/{productId}/variants" \
  -H "Authorization: Bearer shp_your_api_key_here"

Create variant (incremental)

curl -s -X POST "https://www.shopial.com/api/v1/products/{productId}/variants" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TY-12345-S-M",
    "barcode": "869000000003",
    "price": 299.9,
    "compareAtPrice": 349.9,
    "inventory": 4,
    "optionValues": ["Renk::Siyah", "Beden::M"],
    "isDefault": false
  }'

Update variant

curl -s -X PATCH "https://www.shopial.com/api/v1/products/{productId}/variants/{variantId}" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"price": 279.9, "inventory": 8}'

Archive variant

curl -s -X DELETE "https://www.shopial.com/api/v1/products/{productId}/variants/{variantId}" \
  -H "Authorization: Bearer shp_your_api_key_here"

curl -s -X POST "https://www.shopial.com/api/v1/webhooks" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://integrator.example/hooks/shopial","events":["order.paid"]}'

curl -s -X POST "https://www.shopial.com/api/v1/webhooks" \
  -H "Authorization: Bearer shp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://integrator.example/hooks/shopial","events":["order.paid","product.variant.created","product.variant.updated","product.variant.deleted"]}'

Outbound webhooks

Shopial POSTs events to your registered URL.

Supported events:

order.paid
product.variant.created
product.variant.updated
product.variant.deleted

Body is signed with HMAC-SHA256 (endpoint secret or SHOPIAL_WEBHOOK_SIGNING_SECRET).

Webhook headers

X-Shopial-Event: order.paid
X-Shopial-Signature: <hmac-sha256-hex>
X-Shopial-Delivery-Id: <delivery-id>

Error response

Sample JSON

{
  "code": "invalid_body",
  "message": "Invalid product payload",
  "details": { }
}

Hub / integrator note

Platforms such as Yengeç, Sopyo, Entegra, and similar systems wire their own connectors to this API. Shopial standardizes product creation through a universal product core; channel integrations are handled in metadata and adapter layers.

Search

Shopial Integrator API