API documentation

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

Wholesale API

Wholesale Catalog

Browse the wholesale (B2B) marketplace — the sellers offering wholesale stock, the wholesale-enabled products they list, and the full detail of any single product with its variants. These are cross-merchant read endpoints: the signed caller browses other merchants' wholesale catalogue and is always excluded from the sellers list. Every route is HMAC-signed, English-only, and returns money as decimal strings in IQD.

List wholesale sellers

Returns the merchants flagged as wholesale sellers that own at least one active, visible, wholesale-priced product, as a paginated collection newest-first. The calling merchant is always excluded. A top-level categories tree of the wholesale taxonomy is attached alongside the paginated data.

GET /api/v1.0/third-party/wholesale/catalog/sellers

Signed

Query parameters

Field	Type	Required	Description
`search`	string	Optional	Fuzzy match against the seller business_name (max 255 chars).
`category_id`	integer	Optional	Only sellers owning at least one wholesale product in this category id.
`subcategory_id`	integer	Optional	Only sellers owning at least one wholesale product in this subcategory id.

Response

{
    "data": [
        {
            "id": 42,
            "business_name": "Baghdad Wholesale Co.",
            "logo_url": "https://s3.amazonaws.com/gini/merchants/logos/42.png",
            "address": "Baghdad - Karrada"
        }
    ],
    "links": {
        "first": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog/sellers?page=1",
        "last": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog/sellers?page=3",
        "prev": null,
        "next": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog/sellers?page=2"
    },
    "meta": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 15,
        "total": 34
    },
    "categories": [
        {
            "id": 3,
            "name": "Electronics",
            "slug": "electronics",
            "is_active": 1,
            "image_url": "https://s3.amazonaws.com/gini/categories/electronics.jpg",
            "icon_url": "https://s3.amazonaws.com/gini/categories_icons/electronics.png",
            "subcategories": [
                {
                    "id": 12,
                    "name": "Audio",
                    "slug": "audio",
                    "is_active": 1,
                    "image": "https://s3.amazonaws.com/gini/subcategories/audio.jpg"
                }
            ]
        }
    ]
}

Notes

HMAC-signed — the signature resolves the calling merchant, who is always excluded from the sellers list.
A seller appears only when its config is flagged is_b2b_seller and it owns at least one product that is b2b-enabled, visible, and has a non-null b2b_price.
address is a display string built as state_label - nearest_function_point, trimmed when either side is empty.
logo_url falls back to a platform placeholder URL when the seller has no logo set.
Each seller object carries id, business_name, logo_url and address only — the per-seller categories relation is not eager-loaded, so use the top-level categories tree for the wholesale taxonomy.
The top-level categories tree lists only categories (and subcategories) that currently have at least one wholesale product, each ordered by sort_by.
Paginated 15 per page, newest-first. Invalid filter types (e.g. a non-integer category_id) return 422 with a validation errors payload.

List wholesale products

Returns the wholesale-enabled products across every wholesale seller as a paginated collection newest-first. All query parameters are optional filters. List rows carry the seller (as client), the trimmed category, images, and the wholesale-priced variants without their attribute values. The same top-level categories tree is attached alongside the data.

GET /api/v1.0/third-party/wholesale/catalog

Signed

Query parameters

Field	Type	Required	Description
`search`	string	Optional	Fuzzy match against the product name (max 255 chars).
`category_id`	integer	Optional	Filter products by category id.
`subcategory_id`	integer	Optional	Filter products by subcategory id.
`client_id`	integer	Optional	Filter products by the seller merchant id that owns them.

Response

{
    "data": [
        {
            "id": 142,
            "name": "Wireless Headphones",
            "slug": "wireless-headphones",
            "sku": "WH-2026-001",
            "description": "Over-ear Bluetooth headphones with active noise cancellation.",
            "b2b_price": "32000.00",
            "b2b_min_quantity": 10,
            "quantity": 500,
            "category": {
                "id": 3,
                "name": "Electronics",
                "slug": "electronics"
            },
            "client": {
                "id": 42,
                "business_name": "Baghdad Wholesale Co.",
                "logo_url": "https://s3.amazonaws.com/gini/merchants/logos/42.png"
            },
            "image": "https://s3.amazonaws.com/gini/products/142/1.jpg",
            "images": [
                "https://s3.amazonaws.com/gini/products/142/1.jpg",
                "https://s3.amazonaws.com/gini/products/142/2.jpg"
            ],
            "variants": [
                {
                    "id": 1167,
                    "sku": "WH-2026-001-RED",
                    "b2b_price": "33000.00",
                    "quantity": 120
                }
            ]
        }
    ],
    "links": {
        "first": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog?page=1",
        "last": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog?page=8",
        "prev": null,
        "next": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/catalog?page=2"
    },
    "meta": {
        "current_page": 1,
        "last_page": 8,
        "per_page": 15,
        "total": 118
    },
    "categories": [
        {
            "id": 3,
            "name": "Electronics",
            "slug": "electronics",
            "is_active": 1,
            "image_url": "https://s3.amazonaws.com/gini/categories/electronics.jpg",
            "icon_url": "https://s3.amazonaws.com/gini/categories_icons/electronics.png",
            "subcategories": [
                {
                    "id": 12,
                    "name": "Audio",
                    "slug": "audio",
                    "is_active": 1,
                    "image": "https://s3.amazonaws.com/gini/subcategories/audio.jpg"
                }
            ]
        }
    ]
}

Notes

HMAC-signed. Only products that are b2b-enabled, visible, and owned by a merchant flagged is_b2b_seller are returned; ordered newest-first, 15 per page.
client is the seller merchant that owns the product, exposed as id, business_name and logo_url.
b2b_price is a decimal string; b2b_min_quantity is the minimum wholesale order quantity; quantity is the available stock — both integers.
image is the first image absolute S3 URL, or null when the product has no images; images is the full ordered array of absolute S3 URLs.
variants lists only variants that carry a non-null b2b_price. List variants expose id, sku, b2b_price and quantity only — their attribute values are omitted here and returned by the show endpoint.
category is trimmed to id, name and slug on the product; the richer wholesale taxonomy (with subcategories) is attached once at the top level under categories.
search matches the product name, client_id filters by seller merchant id; invalid filter types return 422 with a validation errors payload.

Show wholesale product

Returns the full detail of a single wholesale product, including its wholesale-priced variants with their attribute values. The {id} path segment is the numeric product id — there is no route-model binding, the product is looked up manually. Responds 404 when the id is not a wholesale product.

GET /api/v1.0/third-party/wholesale/catalog/{id}

Signed

Response

{
    "data": {
        "id": 142,
        "name": "Wireless Headphones",
        "slug": "wireless-headphones",
        "sku": "WH-2026-001",
        "description": "Over-ear Bluetooth headphones with active noise cancellation.",
        "b2b_price": "32000.00",
        "b2b_min_quantity": 10,
        "quantity": 500,
        "category": {
            "id": 3,
            "name": "Electronics",
            "slug": "electronics"
        },
        "client": {
            "id": 42,
            "business_name": "Baghdad Wholesale Co.",
            "logo_url": "https://s3.amazonaws.com/gini/merchants/logos/42.png"
        },
        "image": "https://s3.amazonaws.com/gini/products/142/1.jpg",
        "images": [
            "https://s3.amazonaws.com/gini/products/142/1.jpg",
            "https://s3.amazonaws.com/gini/products/142/2.jpg"
        ],
        "variants": [
            {
                "id": 1167,
                "sku": "WH-2026-001-RED",
                "b2b_price": "33000.00",
                "quantity": 120,
                "attributes": [
                    {
                        "id": 5,
                        "product_variant_id": 1167,
                        "product_attribute_id": 5,
                        "value": "Red",
                        "name": "Color"
                    }
                ]
            }
        ]
    }
}

Notes

HMAC-signed. The {id} path segment is the numeric product id; there is no route-model binding.
Returns 404 with a body of {message: This product is not available for wholesale.} when the id does not exist or the product is not b2b-enabled. Success uses the {data: ...} envelope, errors use {message: ...}.
Lookup requires only is_b2b_enabled — unlike the list endpoints it does not re-check visibility or the seller is_b2b_seller flag, and does not exclude the caller.
A single product is returned under data (an object, not an array); this endpoint has no pagination and no top-level categories tree.
variants here additionally include an attributes array; each entry carries id, product_variant_id, product_attribute_id, value and name (e.g. name Color, value Red) sourced from the product_variant_attributes pivot.
Only variants with a non-null b2b_price are included; b2b_price is a decimal string and quantity is the variant stock.
image and images are absolute S3 URLs (image is null when the product has no images), matching the list endpoint.

Previous Webhooks Next Cart