تاجر جني
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
Wholesale API
Buyer orders

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
Catalog Cart Buyer orders Seller orders

Wholesale Buyer Orders

Manage the wholesale orders you place as a buyer — list your purchases, place a new order from your wholesale cart, fetch one order in full detail, confirm you received a delivery, and cancel an order that has not been fulfilled yet. Every route is scoped to the calling signed merchant through their wholesalePurchases relation, so an integration only ever sees and mutates its own orders. All endpoints are HMAC-signed, and writes made through this API do not re-trigger the merchant's own outbound webhook.

List buyer orders

Returns the wholesale orders you have placed, as a paginated collection ordered newest-first. The optional status filter narrows by lifecycle state, plus a synthetic pending_receipt value for delivered orders you have not confirmed as received yet. List rows carry the seller and the order items (with their product), but omit each item's variant and attributes — those appear on the single-order detail endpoint instead.

GET /api/v1.0/third-party/wholesale/orders/buyer
Signed
Query parameters
Field Type Required Description
status string Optional Filter by order status. One of the wholesale statuses pending, accepted, delivered, cancelled, or the synthetic value pending_receipt (delivered orders whose buyer_received_at is still null).
Response 
{
    "data": [
        {
            "id": 4187,
            "status": "delivered",
            "status_label": "Delivered",
            "accepted_at": "2026-06-21 10:42",
            "delivered_at": "2026-06-23 14:05",
            "buyer_received_at": null,
            "total": "225000.000",
            "formatted_total": "IQD 225,000",
            "items": [
                {
                    "id": 9012,
                    "product": {
                        "id": 142,
                        "name": "Wireless Headphones",
                        "slug": "wireless-headphones",
                        "sku": "WH-2026-001",
                        "description": "Over-ear bluetooth headphones",
                        "b2b_price": "45000.00",
                        "b2b_min_quantity": 5,
                        "quantity": 320,
                        "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"
                        ]
                    },
                    "quantity": 5,
                    "unit_price": "45000.000",
                    "formatted_unit_price": "IQD 45,000",
                    "total_price": "225000.000",
                    "formatted_total_price": "IQD 225,000"
                }
            ],
            "cancelled_by": null,
            "cancelled_at": null,
            "created_at": "2026-06-20 09:15",
            "seller": {
                "id": 77,
                "business_name": "Baghdad Wholesale Co",
                "logo_url": "https://s3.amazonaws.com/gini/logos/77.png",
                "business_phone": "+9647701234567"
            }
        }
    ],
    "links": {
        "first": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/orders/buyer?page=1",
        "last": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/orders/buyer?page=3",
        "prev": null,
        "next": "https://merchant.gini.iq/api/v1.0/third-party/wholesale/orders/buyer?page=2"
    },
    "meta": {
        "current_page": 1,
        "last_page": 3,
        "per_page": 15,
        "total": 34
    }
}
Notes
  • Scoped to the signed merchant — only your own wholesale purchases (the wholesalePurchases relation) are returned.
  • Ordered newest-first and paginated with the Laravel default page size (15); pass page to move through results.
  • status accepts the four wholesale statuses (pending, accepted, delivered, cancelled) or pending_receipt, which returns delivered orders whose buyer_received_at is still null.
  • List item rows omit variant and its attributes; call GET /orders/buyer/{id} for the full detail including the ordered variant.
  • Money fields are decimal strings — total, unit_price and total_price are decimal:3, product b2b_price is decimal:2 — and each is mirrored pre-formatted in IQD under formatted_total, formatted_unit_price and formatted_total_price.
  • cancelled_by is buyer or seller (or null); status_label is the human-readable label for status.
  • HMAC-signed like every wholesale endpoint.
Place buyer order

Turns your current wholesale cart into a single Pending order to the cart's seller. Each line's wholesale price and quantity are snapshotted at placement, the wholesale cart is cleared, and the seller is notified. Takes no request body — the cart is the input. Returns the created order in full detail.

POST /api/v1.0/third-party/wholesale/orders/buyer
Signed
Response 
{
    "data": {
        "id": 4192,
        "status": "pending",
        "status_label": "Pending",
        "accepted_at": null,
        "delivered_at": null,
        "buyer_received_at": null,
        "total": "225000.000",
        "formatted_total": "IQD 225,000",
        "items": [
            {
                "id": 9031,
                "product": {
                    "id": 142,
                    "name": "Wireless Headphones",
                    "slug": "wireless-headphones",
                    "sku": "WH-2026-001",
                    "description": "Over-ear bluetooth headphones",
                    "b2b_price": "45000.00",
                    "b2b_min_quantity": 5,
                    "quantity": 320,
                    "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": "45000.00",
                    "quantity": 80,
                    "attributes": [
                        {
                            "id": 55,
                            "product_variant_id": 1167,
                            "product_attribute_id": 3,
                            "value": "Red",
                            "name": "Color"
                        }
                    ]
                },
                "quantity": 5,
                "unit_price": "45000.000",
                "formatted_unit_price": "IQD 45,000",
                "total_price": "225000.000",
                "formatted_total_price": "IQD 225,000"
            }
        ],
        "cancelled_by": null,
        "cancelled_at": null,
        "created_at": "2026-07-06 12:03",
        "seller": {
            "id": 77,
            "business_name": "Baghdad Wholesale Co",
            "logo_url": "https://s3.amazonaws.com/gini/logos/77.png",
            "business_phone": "+9647701234567"
        }
    }
}
Notes
  • Takes no request body — the order is built from your current wholesale cart (the wholesaleCarts items).
  • Creates one Pending order to the cart's seller, snapshots each line's wholesale price and quantity, clears the wholesale cart, and notifies the seller.
  • Stock is NOT decremented at placement — the seller decrements it when they accept, so a pending order that is cancelled or expires never ties up inventory.
  • All cart items must belong to a single wholesale-enabled seller, and you cannot place an order with yourself.
  • Returns 422 with a message key when the order cannot be placed, e.g. Wholesale cart is empty., This seller is not enabled for wholesale., You cannot place an order with yourself., Wholesale cart items must be from the same seller., This product is no longer available for wholesale., This product does not have a wholesale price., This product variant does not have a wholesale price., or Order total exceeds the maximum allowed amount.
  • The success body is the created order in full detail (inside data), the same shape as GET /orders/buyer/{id}.
  • HMAC-signed.
Show buyer order

Returns the full detail for one wholesale order you placed, including its line items with the product, the ordered variant and the variant's attributes, plus the seller. The {id} path segment is the numeric order id — there is no route-model binding, the order is looked up manually and scoped to your purchases.

GET /api/v1.0/third-party/wholesale/orders/buyer/{id}
Signed
Response 
{
    "data": {
        "id": 4187,
        "status": "delivered",
        "status_label": "Delivered",
        "accepted_at": "2026-06-21 10:42",
        "delivered_at": "2026-06-23 14:05",
        "buyer_received_at": null,
        "total": "225000.000",
        "formatted_total": "IQD 225,000",
        "items": [
            {
                "id": 9012,
                "product": {
                    "id": 142,
                    "name": "Wireless Headphones",
                    "slug": "wireless-headphones",
                    "sku": "WH-2026-001",
                    "description": "Over-ear bluetooth headphones",
                    "b2b_price": "45000.00",
                    "b2b_min_quantity": 5,
                    "quantity": 320,
                    "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": "45000.00",
                    "quantity": 80,
                    "attributes": [
                        {
                            "id": 55,
                            "product_variant_id": 1167,
                            "product_attribute_id": 3,
                            "value": "Red",
                            "name": "Color"
                        }
                    ]
                },
                "quantity": 5,
                "unit_price": "45000.000",
                "formatted_unit_price": "IQD 45,000",
                "total_price": "225000.000",
                "formatted_total_price": "IQD 225,000"
            }
        ],
        "cancelled_by": null,
        "cancelled_at": null,
        "created_at": "2026-06-20 09:15",
        "seller": {
            "id": 77,
            "business_name": "Baghdad Wholesale Co",
            "logo_url": "https://s3.amazonaws.com/gini/logos/77.png",
            "business_phone": "+9647701234567"
        }
    }
}
Notes
  • Returns 404 with a message of Wholesale order not found. when the id does not exist or is not one of your purchases.
  • Detail additionally loads each item's variant and its attributes (the pivot product_variant_id, product_attribute_id and value, plus the attribute name); a variantless item omits the variant key.
  • The nested product object omits keys whose columns were not selected — category, client and variants are not returned on order items.
  • seller carries id, business_name, logo_url and business_phone.
  • Money fields follow the same decimal-string rules as the list endpoint, each mirrored under its formatted_ counterpart.
  • HMAC-signed.
Confirm order received

Marks a delivered order as physically received by you. This stamps buyer_received_at and notifies the seller; the order status stays delivered, since received is a sub-state of delivery rather than a separate status. On success it returns a plain confirmation rather than the order.

POST /api/v1.0/third-party/wholesale/orders/buyer/{id}/confirm-received
Signed
Response 
{
    "data": null
}
Notes
  • Returns 404 with a message of Wholesale order not found. when the id is not one of your purchases.
  • Only an order in the delivered status can be confirmed; otherwise 422 with a message of Only delivered orders can be confirmed as received.
  • Confirming an order that is already received returns 422 with a message of This order is already marked as received.
  • On success buyer_received_at is stamped and the seller is notified; the status itself stays delivered.
  • The success body is data set to null — re-fetch GET /orders/buyer/{id} to read buyer_received_at.
  • HMAC-signed.
Cancel buyer order

Cancels one of your wholesale orders. As the buyer you may cancel an order that is still pending or has been accepted; cancelling an accepted order restores the reserved stock to the seller. The order moves to cancelled and the seller is notified. Returns a plain confirmation rather than the order.

POST /api/v1.0/third-party/wholesale/orders/buyer/{id}/cancel
Signed
Response 
{
    "data": null
}
Notes
  • Returns 404 with a message of Wholesale order not found. when the id is not one of your purchases.
  • As the buyer you may cancel an order in the pending OR accepted status; any other status returns 422 with a message of Only pending or accepted orders can be cancelled.
  • Cancelling an accepted order restores the reserved stock back to the seller's products and variants; cancelling a pending order does not, since stock was never taken.
  • On success the order moves to cancelled with cancelled_by set to buyer and cancelled_at stamped, and the seller is notified.
  • The success body is data set to null.
  • HMAC-signed.
Previous Cart Next Seller orders