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

Attributes

Manage product attributes such as Color and Size and their possible values — the building blocks used to generate product variants, scoped to your merchant account and signed with HMAC-SHA256.

List attributes

Lists all product attributes belonging to the authenticated merchant, ordered newest-first. Supports a free-text search on the attribute name via the query parameter.

GET /api/v2.0/third-party/attributes

Signed

Query parameters

Field	Type	Required	Description
`query`	string	Optional	Search attributes whose name contains this value (case-insensitive LIKE match).
`page`	integer	Optional	Page number for pagination. Results are paginated at 15 per page.

Response

[
    {
        "id": 55,
        "name": "Color",
        "type": "color",
        "values": [
            "Red",
            "Blue",
            "Green"
        ]
    },
    {
        "id": 56,
        "name": "Size",
        "type": "select",
        "values": [
            "S",
            "M",
            "L",
            "XL"
        ]
    }
]

Notes

The response is a bare JSON array of attribute objects. No pagination envelope (no data/links/meta wrapper) is returned even though the query is paginated at 15 rows per page.
The page query parameter still offsets the underlying paginator, but because no meta is returned the total page count is not exposed.
Results are ordered by most recently created first.

Get an attribute

Retrieves a single attribute by its numeric id. Returns 404 if the attribute does not exist or does not belong to the authenticated merchant.

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

Signed

Response

{
    "data": {
        "id": 55,
        "name": "Color",
        "type": "color",
        "values": [
            "Red",
            "Blue",
            "Green"
        ]
    }
}

Notes

The path parameter {id} is the numeric attribute id (not a slug or SKU).
A missing or non-owned attribute returns HTTP 404 with {'message': 'Attribute not found'}.

Create an attribute

Creates a new attribute with its possible values for the authenticated merchant. The name must be unique among the merchant's existing attributes.

POST /api/v2.0/third-party/attributes

Signed

Body parameters

Field	Type	Required	Description
`name`	string	Required	Attribute name (max 255 chars). Must be unique per merchant.
`type`	string	Required	Attribute type. Allowed values: color or select.
`values`	array	Required	List of possible values for the attribute (at least 1 item).
`values.*`	string	Required	Each value in the list. Non-empty string, max 255 chars.

Request body

{
    "name": "Color",
    "type": "color",
    "values": [
        "Red",
        "Blue",
        "Green"
    ]
}

Response

{
    "data": {
        "id": 55,
        "name": "Color",
        "type": "color",
        "values": [
            "Red",
            "Blue",
            "Green"
        ]
    }
}

Notes

Returns HTTP 201 on success with the created attribute wrapped in a data object.
type accepts only color or select; any other value fails validation with HTTP 422.
A duplicate name within the same merchant fails validation with HTTP 422.

Update an attribute

Updates an attribute's name, type and values. Values that are currently in use by product variants cannot be removed.

PUT /api/v2.0/third-party/attributes/{id}

Signed

Body parameters

Field	Type	Required	Description
`name`	string	Required	Attribute name (max 255 chars). Must be unique per merchant, ignoring this attribute.
`type`	string	Required	Attribute type. Allowed values: color or select.
`values`	array	Required	Updated full list of values (at least 1 item). This replaces the existing list.
`values.*`	string	Required	Each value in the list. Non-empty string, max 255 chars.

Request body

{
    "name": "Color",
    "type": "color",
    "values": [
        "Red",
        "Blue",
        "Green",
        "Black"
    ]
}

Response

{
    "data": {
        "id": 55,
        "name": "Color",
        "type": "color",
        "values": [
            "Red",
            "Blue",
            "Green",
            "Black"
        ]
    }
}

Notes

values is a full replacement of the existing list, not a partial merge — omit a value to remove it.
Removing a value that is currently referenced by any product variant is rejected with HTTP 422 and a message listing the offending values (e.g. 'Cannot remove values that are used in product variants: Red').
A missing or non-owned attribute returns HTTP 404 with {'message': 'Attribute not found'}.
The name uniqueness check ignores the attribute being updated.

Delete an attribute

Deletes an attribute. Fails if the attribute is still referenced by any product variant.

DELETE /api/v2.0/third-party/attributes/{id}

Signed

Response

{
    "message": "Attribute deleted successfully"
}

Notes

Returns HTTP 422 with {'message': 'Cannot delete this attribute because it has associated products.'} if any product variant references this attribute.
A missing or non-owned attribute returns HTTP 404 with {'message': 'Attribute not found'}.
On success returns HTTP 200 with a confirmation message (no data body).

Previous Products Next Product Variants