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

Wholesale API

Wholesale Cart

Manage the signed merchant's wholesale shopping cart as a buyer — view the current cart with per-line and grand totals, add products or specific variants, change quantities, and remove lines or clear the whole cart. Every route is HMAC-signed and scoped to the calling merchant, who acts as the buyer. Wholesale carts are single-seller: all lines must belong to one seller, so switching sellers means clearing the cart first. Stock is never held at cart-time — it is only decremented when the seller later accepts the placed order.

View cart

Returns every line in the calling merchant's wholesale cart, each with its product and (optional) variant, alongside the line count and the cart grand total. Not paginated — the full cart is returned in one payload. Unit price prefers the variant's wholesale price, falling back to the product's.

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

Signed

Response

{
    "data": {
        "items": [
            {
                "id": 4821,
                "product": {
                    "id": 142,
                    "name": "Wireless Headphones",
                    "slug": "wireless-headphones",
                    "sku": "WH-2026-001",
                    "description": "Over-ear wireless headphones, wholesale carton.",
                    "b2b_price": "38000.00",
                    "b2b_min_quantity": 10,
                    "quantity": 500,
                    "client": {
                        "id": 57,
                        "business_name": "Baghdad Electronics Wholesale",
                        "logo_url": "https://s3.amazonaws.com/gini/merchants/logos/57.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"
                    ]
                },
                "variant": {
                    "id": 1167,
                    "sku": "WH-2026-001-RED",
                    "b2b_price": "40000.00",
                    "quantity": 120
                },
                "quantity": 12,
                "unit_price": "40000.00",
                "formatted_unit_price": "IQD 40,000",
                "total_price": 480000,
                "formatted_total_price": "IQD 480,000"
            }
        ],
        "items_count": 1,
        "total": 480000,
        "formatted_total": "IQD 480,000"
    }
}

Notes

Scoped to the signed merchant, who acts as the buyer — only the caller's own wholesale cart lines are returned.
unit_price prefers the variant's b2b_price, falling back to the product's b2b_price, then to 0.
b2b_price and unit_price are stored decimal strings (e.g. 40000.00); total_price and the cart total are computed numbers; formatted_* fields are pre-rendered in IQD (e.g. IQD 480,000).
On a variantless line the variant key is null and unit_price is taken from the product's b2b_price.
The product object omits category and variants here — they are not eager-loaded on the cart payload — and the variant omits its attributes for the same reason.
An empty cart returns items as an empty array with items_count 0 and total 0.

Add item to cart

Adds a product, or a specific variant of it, to the wholesale cart. If the same product/variant is already in the cart the quantities are combined. On success the endpoint returns an empty data envelope rather than the added line — re-fetch the cart to read it.

POST /api/v1.0/third-party/wholesale/cart

Signed

Body parameters

Field	Type	Required	Description
`product_id`	integer	Required	Id of the product to add. Must reference an existing, wholesale-enabled, visible product.
`product_variant_id`	integer	Optional	Id of a specific variant to add. Omit for a variantless product; when set, the variant must belong to the product and carry its own wholesale price.
`quantity`	integer	Required	Quantity to add, at least 1. The resulting line quantity must meet the product's minimum wholesale quantity and stay within available stock.

Request body

{
    "product_id": 142,
    "product_variant_id": 1167,
    "quantity": 12
}

Response

{
    "data": null
}

Notes

On success the body is {'data': null} — the added line is not echoed back; re-fetch the cart with GET /cart to read it.
Wholesale carts are single-seller: once the cart holds a line, every further add must be from the same seller, otherwise the request fails with 422 and a message prompting you to clear the cart first.
The product must be wholesale-enabled (is_b2b_enabled with a b2b_price set) and visible, and the seller must be enabled as a wholesale seller, or the add fails with 422.
You cannot add your own products to the cart.
Quantity is validated as existing-cart-quantity plus the added quantity: it must be at least the product's b2b_min_quantity and cannot exceed available stock — for a variant, the variant's own wholesale price and stock are checked.
Stock is not decremented at add-time — it is only decremented when the seller later accepts the placed order.
Business-rule failures return 422 with {'message': ...}; malformed input (missing product_id, quantity under 1, unknown product or variant id) returns 422 with a validation-error body.

Update cart item quantity

Changes the quantity of a single cart line owned by the caller. The type field decides whether the given quantity replaces, adds to, or subtracts from the current line quantity. On success the endpoint returns the stored line quantity after the change.

PUT /api/v1.0/third-party/wholesale/cart/{cartItem}

Signed

Body parameters

Field	Type	Required	Description
`quantity`	integer	Required	The quantity value applied per the type field, at least 1.
`type`	string	Optional	How to apply quantity: set (the default) replaces the line quantity, + increments by quantity, and - decrements by quantity. One of set, +, -.

Request body

{
    "quantity": 2,
    "type": "+"
}

Response

{
    "data": {
        "quantity": 14
    }
}

Notes

The {cartItem} path segment is the numeric cart-line id; it must belong to the caller or the response is 404 with {'message': 'Cart item not found.'}.
type controls how quantity is applied: set (default) replaces the line quantity, + adds to it, and - subtracts from it.
Reducing the resulting quantity to 0 or under removes the line entirely; the endpoint still returns 200.
The resulting quantity must be at least the product's b2b_min_quantity and cannot exceed available stock, otherwise 422 with {'message': ...}.
On success the body is {'data': {'quantity': ...}} echoing the stored line quantity after the change.

Remove cart item

Removes a single line from the wholesale cart. The line must belong to the caller. On success the endpoint returns an empty data envelope.

DELETE /api/v1.0/third-party/wholesale/cart/{cartItem}

Signed

Response

{
    "data": null
}

Notes

The {cartItem} path segment is the numeric cart-line id; it must belong to the caller or the response is 404 with {'message': 'Cart item not found.'}.
On success the body is {'data': null}.
Removing a line that is already gone (or never belonged to you) returns 404 rather than a silent success.

Clear cart

Deletes every line in the calling merchant's wholesale cart in a single call. Useful for switching sellers, since the cart is single-seller. Takes no parameters.

DELETE /api/v1.0/third-party/wholesale/cart

Signed

Response

{
    "data": null
}

Notes

Deletes all lines in the caller's wholesale cart at once; there are no parameters and no request body.
Always returns 200 with {'data': null}, even when the cart was already empty.
Use this to switch sellers, since a wholesale cart may only hold lines from a single seller.

Previous Catalog Next Buyer orders