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

Profile Categories Products Attributes Product Variants Product Add-ons Discounts Orders Abandoned carts Reviews Notifications Collections Reels Influencers Exports Webhooks

API reference

Exports

Queue an asynchronous Excel export of your orders or products, then poll the status endpoint until the pre-signed download link is ready. All three endpoints are HMAC-signed and scoped to the authenticated merchant.

Export Orders

Queues an asynchronous Excel (.xlsx) export of the authenticated merchant's orders. Accepts the same filter parameters as GET /orders (per_page is ignored). Returns 202 Accepted with an export_id and status pending; a queued job then flips the export through processing to completed (or failed). Poll GET /exports/{id} to retrieve the download link. Send an empty body to export all orders.

POST /api/v2.0/third-party/exports/orders

Signed

Body parameters

Field	Type	Required	Description
`search`	string	Optional	Free-text search across orders (max 255 chars). Same behavior as GET /orders.
`status`	string	Optional	Filter by order status. One of: pending, accepted, rejected, on_the_way, delivered, cancelled, refunded, returned, delayed, rwa, expired, temp_cancelled.
`date`	string	Optional	Filter orders by a single date (YYYY-MM-DD).
`payment_method`	string	Optional	Filter by payment method. One of: e_payment, aqsati, cash_on_delivery, qi_payment, ratibi, ishtrelk, post_paid, dots.
`state`	integer	Optional	Governorate/state id to filter orders by.
`product_slug`	string	Optional	Restrict to orders that contain the product with this slug.
`late_orders`	string	Optional	Filter to late orders. One of: enabled, disabled.
`per_page`	integer	Optional	Validated (1-100) but IGNORED for exports — an export always includes the full filtered set, not a page.

Request body

{
    "status": "delivered",
    "date": "2026-02-10"
}

Response

{
    "data": {
        "export_id": 42,
        "type": "orders",
        "status": "pending",
        "created_at": "2026-02-11T12:00:00+03:00"
    }
}

Notes

Returns HTTP 202 Accepted — the export is queued, not built inline. The response never carries a download_url on this call (status is always pending).
Order export uses a fixed column set (no column picker): id, product, variant, customer, phone, status, payment_method, completed_at, ordered_at, amount, quantity, governorate, city, address, influencer.
per_page is stripped from the filters server-side, so paging inputs have no effect on the export.
Send an empty JSON body to export every order for the merchant.
Poll GET /exports/{export_id} until status is completed or failed to obtain the file.
Signed like the rest of the V2 third-party API (API key + HMAC-SHA256 header signature).

Export Products

Queues an asynchronous Excel (.xlsx) export of the authenticated merchant's products. Accepts the same filter parameters as GET /products (per_page is ignored). Returns 202 Accepted with an export_id and status pending. Poll GET /exports/{id} for the download link. Send an empty body or a blank search to export all products.

POST /api/v2.0/third-party/exports/products

Signed

Body parameters

Field	Type	Required	Description
`search`	string	Optional	Search products by name/SKU (max 255 chars). Same behavior as GET /products.
`per_page`	integer	Optional	Validated (1-100) but IGNORED for exports — an export always includes the full filtered set, not a page.

Request body

{
    "search": "headphones"
}

Response

{
    "data": {
        "export_id": 43,
        "type": "products",
        "status": "pending",
        "created_at": "2026-02-11T12:00:00+03:00"
    }
}

Notes

Returns HTTP 202 Accepted — same async flow and response shape as Export Orders.
Product export uses a fixed column set: name, sku, price, quantity, category, subcategory, visibility, created_at.
per_page is stripped from the filters server-side and has no effect on the export.
Send an empty JSON body (or a blank search) to export every product.
Poll GET /exports/{export_id} until status is completed or failed to obtain the file.

Export Abandoned Carts

Queues an .xlsx of the carts customers left behind, one row per cart LINE — the list endpoint groups by customer, the spreadsheet does not. Accepts the same filters as GET /abandoned-carts. Returns 202 with an export_id to poll.

POST /api/v2.0/third-party/exports/abandoned-carts

Signed

Body parameters

Field	Type	Required	Description
`search`	string	Optional	Match the customer name or phone, or the product in the cart.
`hours`	integer	Optional	Only carts untouched for at least this many hours.
`product_id`	integer	Optional	Only carts containing this product.

Export Wholesale Orders

Queues an .xlsx of the wholesale orders other merchants have placed with you — the seller side. The wholesale route group carried no export at all before this. Returns 202 with an export_id to poll.

POST /api/v2.0/third-party/exports/wholesale-orders

Signed

Body parameters

Field	Type	Required	Description
`status`	string	Optional	Filter by lifecycle status: pending, accepted, delivered or cancelled.
`search`	string	Optional	Match the buyer.
`columns`	array	Optional	Columns to include, returned in the canonical order: id, buyer, buyer_phone, status, total, items_count, pieces_count, ordered_at, accepted_at, delivered_at, received_at, cancelled_at, cancelled_by. Omit for all of them.

Export Stock Template

Queues the restock spreadsheet: every product with its current price and quantity, plus blank "new" columns to fill in. Accepts the same filters as GET /products, so you can pull a template for one branch or only for what is running low.

POST /api/v2.0/third-party/exports/stock-template

Signed

Body parameters

Field	Type	Required	Description
`include_variants`	boolean	Optional	Add a row per variant beneath each product. Defaults to false.
`stock`	string	Optional	in, low or out — the same stock facet GET /products takes.
`branch_id`	integer	Optional	Only products assigned to this branch.

Notes

Every GET /products filter is accepted here, not only the three listed above.
per_page is validated but ignored — an export always covers the full filtered set.

Check Export Status (Poll)

Polls the status of a previously requested export by its id. Returns the export record; when status is completed, the payload additionally includes a short-lived pre-signed download_url for the .xlsx file. Exports are scoped to the authenticated merchant — polling an id that does not exist or belongs to another merchant returns 404.

GET /api/v2.0/third-party/exports/{id}

Signed

Response

{
    "data": {
        "export_id": 42,
        "type": "orders",
        "status": "completed",
        "created_at": "2026-02-11T12:00:00+03:00",
        "download_url": "https://your-bucket.s3.amazonaws.com/exports/api/17/orders-2026-02-11-120500.xlsx?X-Amz-Expires=900&X-Amz-Signature=..."
    }
}

Notes

{id} is the export_id returned by the POST export call — it is a path segment, not a query parameter.
status progresses pending, then processing, then completed (or failed). Poll until it is completed or failed; recommended interval 2-5 seconds.
download_url is only present when status is completed AND the file exists. It is a pre-signed link to a PRIVATE bucket (exports contain customer PII) valid for 15 MINUTES, and is regenerated on every poll — so re-poll to get a fresh URL if it expires.
The response body contains only: export_id, type, status, created_at, and (conditionally) download_url. It does NOT return an expires_at field.
File format is always .xlsx. The generated file is retained on the private disk for ~24 hours, after which it is no longer downloadable.
While pending/processing/failed, the download_url key is simply absent from the payload.
Not found returns HTTP 404 with body {'message': 'Export not found.'} — this also covers exports owned by a different merchant.
Signed with API key + HMAC-SHA256 header signature.

Previous Dashboard stats Next Webhooks