تاجر جني
Which API?
Merchant API For merchants: manage your own catalogue, orders and finances through the v2 Third-Party API. Application API For partner apps: browse Gini merchants and products, send customers to checkout and follow their orders.

New: Application API docs

Pick the API you are reading here — the Merchant API for your own store, the Application API for partner apps.

Merchant dashboard
Getting started
Introduction

API documentation

Everything you need to integrate with the Gini v2 Third-Party API.

Getting started API reference Store API Finance API Settings API Insights API Wholesale API Resources
Introduction Authentication Idempotency Postman collection Troubleshooting

Introduction

The Gini v2 Third-Party API lets you manage your catalog, orders, exports, and webhooks programmatically. Every request is authenticated with an API key and an HMAC-SHA256 signature. This reference documents every endpoint, its parameters, and example responses.

Base URL

Every path in this reference is written in full, from the host onwards — copy them as shown rather than joining them to a base. Version prefixes differ by endpoint: most sit under v2.0, the wholesale endpoints under v1.0 for historical reasons, and both are authenticated the same way.

The path you sign must be the exact path you request, including which version prefix it carries. Signing /api/v2.0/… for a wholesale endpoint that lives at /api/v1.0/… fails as an invalid signature, not as a missing route.
Getting started
1

Get your credentials. Generate your API Client ID and secret from Settings → Integrations. The secret stays retrievable there, so you can look it up again rather than re-issuing credentials. Treat that page as sensitive: anyone who can open your dashboard can read the key.

2

Sign every request. Attach the X-API-KEY, X-TIMESTAMP, and X-SIGNATURE headers described in Authentication.

3

Call the API. Start with a signed GET to /api/v2.0/third-party/ping — a 200 proves the edge, your key and your signature all work. If it fails, Troubleshooting tells you which one from its answer.

Quick example

A signed GET request listing your products. See Authentication for how X-SIGNATURE is computed.

cURL 
curl https://merchant.gini.iq/api/v2.0/third-party/products \
  -H "X-API-KEY: {your_api_client_id}" \
  -H "X-TIMESTAMP: 1739270400" \
  -H "X-SIGNATURE: {hmac_sha256_hex}"
Conventions
  • Every endpoint is signed — there are no public endpoints. See Authentication.
  • Most list endpoints paginate with per_page (1 to 100; default 15, except notifications 20) and page query parameters, and wrap the rows as {data, links, meta}.
  • Five lists do not follow that shape, so do not assume it: categories returns {data} and is not paginated; discounts and attributes return a bare top-level JSON array with no envelope at all; abandoned-carts and the wholesale buyers directory return {data, meta} with no links, because their rows are an aggregate rather than a model query.
  • meta carries current_page, last_page, per_page, total, from, to, path and a links array of page descriptors ({url, label, page, active}). The top-level links object is separate and carries first, last, prev and next. from and to are null on an empty page.
  • The API is stateless — no cookies or sessions. Each request is authenticated on its own.
  • Response messages are always in English regardless of your dashboard language — the API is a machine-facing contract.
  • Writes made through this API never re-fire your own webhooks, so you will not get an event for your own change.
  • Newly uploaded images may take a few minutes to propagate to the CDN even though the API returns the URL immediately.
Next Authentication