Skip to main content

Categories & Pre-offers

This page provides comprehensive information and documentation on a set of API methods specifically designed to handle categories and pre-offers.

Categories​

A category refers to a hierarchical structure that is used to group similar products or services. Each category represents a specific category of products or services within the marketplace and may include one or more subcategories that further define and refine the products or services within that category.

Each category has attributes, which defines the specific characteristics of a product within that category.

Categories are created and managed by the marketplace owner in Omnitron. The marketplace owner can create, update, and delete category nodes as needed.

Sellers can change the attribute value of a product with respect to themselves if the attribute has "is_offer": true parameter in itself. This parameter enables Sellers to enter custom attribute values for the same product.

Schema​

{
    "id": "uuid",
    "name": "string",
    "path": "string",
    "attributes": [
        {
            "key": "string",
            "name": "string",
            "data_type": "enum(text, email, text_area, date, datetime, boolean, valuelabel, dropdown, multiple, price, nested_object, image, file, model, bundle)",
            "default_value": "depends on data_type",
            "values": [
                {"label": "string", "value": "string", "translations": "object"}
            ],
            "is_required": "boolean",
            "is_offer": "boolean",
            "is_variant": "boolean",
            "is_variant_listable": "boolean",
            "is_localizable": "boolean",
            "translations": {"language": {"name":  "value"}}
        }
    ],
    "created_at": "datetime",
    "updated_at": "datetime"
}

Retrieve CTI01​

curl -X GET "https://example.com/api/i1/categories/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "7cbbb704-d86e-4dd2-a962-9dab078d9ff3",
            "name": "Sample Category > Category #1",
            "path": "00010001",
            "attributes": [
                {
                    "key": "foo",
                    "name": "foo",
                    "data_type": "text",
                    "default_value": null,
                    "values": null,
                    "is_required": true,
                    "is_offer": false,
                    "is_variant": false,
                    "is_variant_listable": false,
                    "is_localizable": false,
                    "translations": null
                },
                {
                    "key": "baz",
                    "name": "baz",
                    "data_type": "dropdown",
                    "default_value": null,
                    "values": [
                        {"label": "bar", "value": "bar", "translations": {}},
                        {"label": "qux", "value": "qux", "translations": {}}
                    ],
                    "is_required": true,
                    "is_offer": true,
                    "is_variant": false,
                    "is_variant_listable": false,
                    "is_localizable": false,
                    "translations": null
                }
            ],
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Available Query Parameters

KeyType
namestring
name__containsstring
name__icontainsstring (case-insensitive)
pathstring
path__startswithstring
created_at__gtedatetime
created_at__gtdatetime
created_at__ltedatetime
created_at__ltdatetime
updated_at__gtedatetime
updated_at__gtdatetime
updated_at__ltedatetime
updated_at__ltdatetime

Possible HTTP Status Codes

  • 200 OK: Categories retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Pre-offers​

Pre-offer structure allows sellers to enter their offers including corresponding product information, into Seller Center. Once the pre-offer has been reviewed and approved by the marketplace owner, it will be converted into a listable product with a related offer and made available within the marketplace for buyers to view and purchase.

Schema​

{
    "id": "uuid",
    "sku": "string",
    "name": "string",
    "base_code": "string",
    "category": "uuid (Ref: Category ID)",
    "attributes": {
        "key": "value"
    },
    "product": "uuid",
    "approval_status": "enum(Rejected > 0, Approved > 1, Pending Approval > 2, Approval Required > 3)",
    "prices": [
        {
            "price_list": "uuid (Ref: Price List ID)",
            "price": "decimal",
            "retail_price": "decimal",
            "currency_type": "enum(TRY, USD, EUR, EGP, GBP, MAD, PLN, SAR, RON, UAH, CZK, HUF, RUB, BGN, IQD, KWD, BHD, OMR, QAR, AED, NGN)",
            "tax_rate": "decimal",
            "discount_percentage": "decimal"
        }
    ],
    "stocks": [
        {
            "stock_list": "uuid (Ref: Stock List ID)",
            "stock": "integer",
            "unit_type": "string"
        }
    ],
    "created_at": "datetime",
    "updated_at": "datetime"
}

Upsert PFI01​

If the SKU of the pre-offer already exists, the pre-offer will be updated. Otherwise, a new pre-offer will be created.

curl -X POST 'https://example.com/api/i1/pre-offers/' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: application/json' \
-d '{
    "sku": "SP-A",
    "name": "Sample Product",
    "base_code": "SP",
    "category": "7cbbb704-d86e-4dd2-a962-9dab078d9ff3",
    "approval_status": 3,
    "attributes": {
        "foo": "bar",
        "baz": "qux"
    },
    "prices": [
        {
            "price_list": "4f61bf48-7f9f-49a5-b5be-ea55b020e058",
            "price": "10.00",
            "retail_price": "10.00",
            "currency_type": "USD",
            "tax_rate": "0.00",
            "discount_percentage": "0.00"
        }
    ],
    "stocks": [
        {
            "stock_list": "3ae40ae9-2f60-45cf-8282-91b0a8abc5a8",
            "stock": 100,
            "unit_type": "qty"
        }
    ]
}'

Example Response

{
    "id": "5802e57f-22b7-40e4-95e9-423fc2e1cd80"
}

Possible HTTP Status Codes

  • 200 OK: Pre-offer created/updated successfully.
  • 400 Bad Request: Invalid request body (missing required fields, invalid format, etc.).
    • If the request body contain missing required fields, the response will be in the following format:
      {
          "field": [
              "This field is required."
          ],
          "code": "invalid"
      }
    • If the request body contain missing attributes, the response will be in the following format:
      {
          "detail": "Product is not valid, missing attributes: ATTRIBUTE_KEY",
          "code": "product_is_not_valid_missing_attributes"
      }
  • 406 Not Acceptable: Invalid request headers (invalid format, etc.).
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Retrieve PFI02​

curl -X GET "https://example.com/api/i1/pre-offers/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "5802e57f-22b7-40e4-95e9-423fc2e1cd80",
            "sku": "SP-A",
            "name": "Sample Product",
            "base_code": "SP",
            "category": "7cbbb704-d86e-4dd2-a962-9dab078d9ff3",
            "attributes": {
              "foo": "bar",
              "baz": "qux"
            },
            "meta": "e2ebbb76-de1c-4c03-b33a-1ea03db19ebe",
            "product": null,
            "approval_status": 3,
            "prices": [
                {
                    "price_list": "4f61bf48-7f9f-49a5-b5be-ea55b020e058",
                    "price": "10.00",
                    "retail_price": "10.00",
                    "currency_type": "USD",
                    "tax_rate": "0.00",
                    "discount_percentage": "0.00"
                }
            ],
            "stocks": [
                {
                    "stock_list": "3ae40ae9-2f60-45cf-8282-91b0a8abc5a8",
                    "stock": 100,
                    "unit_type": "qty"
                }
            ],
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Available Query Parameters

KeyType
namestring
name__containsstring
name__icontainsstring (case-insensitive)
base_codestring
base_code__containsstring
base_code__icontainsstring (case-insensitive)
skustring
sku__containsstring
sku__icontainsstring (case-insensitive)
categorystring
category__containsstring
approval_statusinteger
attributes__{KEY}string
attributes{KEY}containsstring
attributes{KEY}startswithstring
attributes{KEY}endswithstring
attributes{KEY}isnullboolean
created_at__gtedatetime
created_at__gtdatetime
created_at__ltedatetime
created_at__ltdatetime
updated_at__gtedatetime
updated_at__gtdatetime
updated_at__ltedatetime
updated_at__ltdatetime

Possible HTTP Status Codes

  • 200 OK: Pre-offers retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Pre-offer Images​

Pre-offer Images represent images that are associated with a related pre-offer product. Once the pre-offer has been reviewed and approved by the marketplace owner, it will be converted into a Product Image instance.

Schema​

{
    "id": "uuid",
    "*parent": "string (Ref: Pre Offer SKU)",
    "*image": "file",
    "height": "integer",
    "width": "integer",
    "order": "integer",
    "hash": "string",
    "status": "enum(Active > 1, Disabled > 0)",
    "created_at": "datetime",
    "updated_at": "datetime"
}

Note 1: * fields are mandatory.

Note 2: Status is by default 1.

Upsert PFI03​

If the hash value of the image matches with an existing image in the system, the system will update it with the given values. On the other hand, if there is no match, the system will create a new image with the provided values.

curl -X POST 'https://example.com/api/i1/pre-offer-images/' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: multipart/form-data' \
-F 'parent="SP-A"' \
-F 'order=1' \
-F 'status=1' \
-F 'image=@"image.png"'

Example Response

{
  "id": "5df61cca-3a22-48ae-83b4-70c0f5cfa29b"
}

Possible HTTP Status Codes

  • 200 OK: Pre-offer Image created/updated successfully.

  • 400 Bad Request: Invalid request body (missing required fields, invalid format, etc.).

    • If the request body contain missing required fields, the response will be in the following format:

      {
          "field": [
              "This field is required."
          ],
          "code": "invalid"
      }

    • If the request body contain corrupted image file such as invalid binary, invalid format etc., the response will be in the following format:

      {
          "detail": "Product image was either not an image or a corrupted image.",
          "code": "corrupted_image"
      }

    • If the request body contain an image file that exceeds size limits, the response will be in the following format:

      {
          "detail": "Image width and height must be lower 2000px.",
          "code": "image_invalid_dimension"
      }

  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).

  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).

  • 500 Internal Server Error: Unexpected server error.

Retrieve PFI04​

curl -X GET "https://example.com/api/i1/pre-offer-images/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "5df61cca-3a22-48ae-83b4-70c0f5cfa29b",
            "parent": "SP-A",
            "image": "https://example.com/path/to/image/a36128c0-dd29-4a0f-a7f4-a0f4ca69508e.jpg",
            "height": 250,
            "width": 250,
            "order": 0,
            "hash": "363cba3185bc4d3e643819941fed4dd2",
            "status": 1,
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Available Query Parameters

KeyType
parentstring
parent__containsstring
parent__icontainsstring (case-insensitive)
orderinteger
statusinteger
created_at__gtedatetime
created_at__gtdatetime
created_at__ltedatetime
created_at__ltdatetime
updated_at__gtedatetime
updated_at__gtdatetime
updated_at__ltedatetime
updated_at__ltdatetime

Possible HTTP Status Codes

  • 200 OK: Pre-offer Images retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Downloadable Pre-offer Images​

A Downloadable Pre-offer Image represents an image that will be converted into a Pre Offer Image instance after fetching the content from the given URL. Once the pre-offer has been reviewed and approved by the marketplace owner, it will be converted into a Product Image instance.

Schema​

{
    "id": "uuid",
    "*url": "uuid",
    "*pre_offer": "string (Ref: Pre Offer SKU)",
    "parent": "string (Ref: Product Image ID)",
    "status": "enum(Pending > 1, Processing > 2, Succeeded > 3, Failed > 4)",
    "created_at": "datetime",
    "updated_at": "datetime"
}

Note 1: * fields are mandatory.

Note 2: Status is by default 1.

Insert PFI07​

curl -X POST 'https://example.com/api/i1/downloadable-pre-offer-images/' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: multipart/form-data' \
-d '[
  {
      "url": "https://akinon.com/images/SP-A-1.png",
      "pre_offer": "SP-A"
  },
  {
      "url": "https://akinon.com/images/SP-A-2.png",
      "pre_offer": "SP-A"
  },
  {
      "url": "https://akinon.com/images/SP-B-1.png",
      "pre_offer": "SP-B"
  },
  {
      "url": "https://akinon.com/images/SP-B-2.png",
      "pre_offer": "SP-B"
  }
]'

Possible HTTP Status Codes

  • 204 No Content: Downloadable Pre-offer Image created successfully.
  • 400 Bad Request: Invalid request body (missing required fields, invalid format, etc.).
    • If the request body contain missing required fields, the response will be in the following format:
      {
          "field": [
              "This field is required."
          ],
          "code": "invalid"
      }
    • If the request body contain corrupted image file such as invalid binary, invalid format etc., the response will be in the following format:
      {
          "detail": "Product image was either not an image or a corrupted image.",
          "code": "corrupted_image"
      }
    • If the request body contain an image file that exceeds size limits, the response will be in the following format:
      {
          "detail": "Image width and height must be lower 2000px.",
          "code": "image_invalid_dimension"
      }
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Retrieve PFI08​

curl -X GET "https://example.com/api/i1/downloadable-pre-offer-images/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "6fccbfc4-2182-4e96-9f6f-c677a9eff2ea",
            "url": "https://via.placeholder.com/250?text=SP",
            "pre_offer": "SP-A",
            "parent": "733cd299-6917-41dc-b7c9-078aa7a14559",
            "error": null,
            "status": 3,
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Possible HTTP Status Codes

  • 200 OK: Downloadable Pre-offer Images retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Pre-offer Videos​

Pre-offer Videos represent videos that are associated with a related pre-offer product. Once the pre-offer has been reviewed and approved by the marketplace owner, it will be converted into a Product Video instance.

Schema​

{
    "id": "uuid",
    "*parent": "string (Ref: Pre Offer SKU)",
    "*video": "file",
    "hash": "string",
    "order": "integer",
    "status": "enum(Active > 1, Disabled > 0)",
    "created_at": "datetime",
    "updated_at": "datetime"
}

Note 1: * fields are mandatory.

Note 2: Status is by default 1.

Upsert PFI05​

If the hash value of the video matches with an existing video in the system, the system will update it with the given values. On the other hand, if there is no match, the system will create a new video with the provided values.

curl -X POST 'https://example.com/api/i1/pre-offer-videos/' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: multipart/form-data' \
-F 'parent="SP-A"' \
-F 'order=1' \
-F 'status=1' \
-F 'video=@"video.mp4"'

Possible HTTP Status Codes

  • 200 OK: Pre-offer Video created/updated successfully.

  • 400 Bad Request: Invalid request body (missing required fields, invalid format, etc.).

    • If the request body contain missing required fields, the response will be in the following format:

      {
          "field": [
              "This field is required."
          ],
          "code": "invalid"
      }

  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).

  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).

  • 500 Internal Server Error: Unexpected server error.

Retrieve PFI06​

curl -X GET "https://example.com/api/i1/pre-offer-videos/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "5df61cca-3a22-48ae-83b4-70c0f5cfa29b",
            "parent": "SP-A",
            "video": "https://example.com/path/to/video/fb3fe746-3117-4536-bddb-df650443a269.mp4",
            "order": 1,
            "hash": "d9061d3da8601932e98f79ec8ba1c877",
            "status": 1,
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Available Query Parameters

KeyType
parentstring
parent__containsstring
parent__icontainsstring (case-insensitive)
orderinteger
statusinteger
created_at__gtedatetime
created_at__gtdatetime
created_at__ltedatetime
created_at__ltdatetime
updated_at__gtedatetime
updated_at__gtdatetime
updated_at__ltedatetime
updated_at__ltdatetime

Possible HTTP Status Codes

  • 200 OK: Pre-offer Videos retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.

Downloadable Pre-offer Videos​

A Downloadable Pre-offer Video represents an image that will be converted into a Pre Offer Video instance after fetching the content from the given URL. Once the pre-offer has been reviewed and approved by the marketplace owner, it will be converted into a Product Video instance.

Schema​

{
    "id": "uuid",
    "*url": "uuid",
    "*pre_offer": "string (Ref: Pre Offer SKU)",
    "parent": "string (Ref: Product Video ID)",
    "status": "enum(Pending > 1, Processing > 2, Succeeded > 3, Failed > 4)",
    "created_at": "datetime",
    "updated_at": "datetime"
}

Note 1: * fields are mandatory.

Note 2: Status is by default 1.

Insert PFI09​

curl -X POST 'https://example.com/api/i1/downloadable-pre-offer-videos/' \
-H 'Authorization: Bearer {TOKEN}' \
-H 'Content-Type: multipart/form-data' \
-d '[
    {
        "url": "https://akinon.com/videos/SP-A-1.mp4",
        "pre_offer": "SP-A"
    },
    {
        "url": "https://akinon.com/videos/SP-A-2.mp4",
        "pre_offer": "SP-A"
    },
    {
        "url": "https://akinon.com/videos/SP-B-1.mp4",
        "pre_offer": "SP-B"
    },
    {
        "url": "https://akinon.com/videos/SP-B-2.mp4",
        "pre_offer": "SP-B"
    }
]'

Possible HTTP Status Codes

  • 204 No Content: Downloadable Pre-offer Video created successfully.

  • 400 Bad Request: Invalid request body (missing required fields, invalid format, etc.).

    • If the request body contain missing required fields, the response will be in the following format:

      {
          "field": [
              "This field is required."
          ],
          "code": "invalid"
      }

    • If the request body contain corrupted video file such as invalid binary, invalid format etc., the response will be in the following format:

      {
          "detail": "Product video was either not an video or a corrupted video.",
          "code": "corrupted_video"
      }

  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).

  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).

  • 500 Internal Server Error: Unexpected server error.

Retrieve PFI10​

curl -X GET "https://example.com/api/i1/downloadable-pre-offer-videos/" \
-H "Content-Type: application/json" \
-H "Authentication: Bearer {TOKEN}"

Example Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "6fccbfc4-2182-4e96-9f6f-c677a9eff2ea",
            "url": "https://via.placeholder.com/250?text=SP",
            "pre_offer": "SP-A",
            "parent": "733cd299-6917-41dc-b7c9-078aa7a14559",
            "error": null,
            "status": 3,
            "created_at": "2019-01-01T00:00:00Z",
            "updated_at": "2019-01-01T00:00:00Z"
        }
    ]
}

Possible HTTP Status Codes

  • 200 OK: Downloadable Pre-offer Videos retrieved successfully.
  • 401 Unauthorized: Invalid authentication header (missing, invalid value, etc.).
  • 415 Unsupported Media Type: Invalid content-type header (missing, invalid format, etc.).
  • 500 Internal Server Error: Unexpected server error.