Takealot API

Introduction

This documentation provides a comprehensive reference for the Takealot Seller API (v2). It includes full details on endpoints, parameters, request bodies, and response schemas including all available fields.

Get offers

GET /v2/offers

Get all offers (v2)

Retrieve information about your offers on the Takealot platform.

Parameters

Name In Type Description
page_number query integer The page number to retrieve (starting at 1).
page_size query integer The number of offers per page. Limited to 100.
offer_ids query array[integer] A list of offer ids to retrieve.

Response (200 OK)

{
  "total_results": 0,
  "page_size": 0,
  "page_number": 0,
  "offers": [
    {
      "tsin_id": 0,
      "offer_id": 0,
      "sku": "string",
      "barcode": "string",
      "product_label_number": "string",
      "selling_price": 0,
      "rrp": 0,
      "leadtime_days": 0,
      "leadtime_stock": [
        {
          "merchant_warehouse": {
            "warehouse_id": 0,
            "name": "string"
          },
          "quantity_available": 0
        }
      ],
      "status": "string",
      "title": "string",
      "offer_url": "string",
      "stock_cover": [
        {
          "warehouse_id": 0,
          "stock_cover_days": 0
        }
      ],
      "sales_units": [
        {
          "warehouse_id": 0,
          "sales_units": 0
        }
      ],
      "discount": "string",
      "discount_shown": true,
      "storage_fee_eligible": true,
      "date_created": "string",
      "stock_at_takealot_total": 0,
      "stock_at_takealot": [
        {
          "warehouse": {
            "warehouse_id": 0,
            "name": "string"
          },
          "quantity_available": 0
        }
      ],
      "stock_on_way": [
        {
          "warehouse": {
            "warehouse_id": 0,
            "name": "string"
          },
          "quantity_available": 0
        }
      ],
      "total_stock_on_way": 0,
      "total_stock_cover": 0,
      "catalogue_quality_score": 0
    }
  ]
}

Error Responses

400 Bad Request 
{ "message": "string" }
403 Forbidden 
{ "message": "string" }
500 Server Error 
{ "message": "string" }

Get offers count

GET /v2/offers/count

Get offers count (v2)

Retrieve the total number of your offers on the Takealot platform (optionally filtered by offer status)

Parameters

NameInTypeDescription
offer_statuses query array[string] A list of offer statuses to filter by. Example - ?offer_statuses=Buyable,Not Buyable
Available values: Buyable, Not Buyable, Disabled by Seller, Disabled by Takealot

Response (200 OK)

{
  "count": 0
}

Get an offer

GET /v2/offers/offer/{identifier}

Get an offer (v2)

Retrieve information about an individual offer by providing an identifier for the offer

Parameters

NameInTypeDescription
identifier * path string Either Takealot's Offer ID, the Barcode or your SKU for the offer. Prepend with ID, Barcode, or SKU. e.g. ID234, BARCODE3223, SKUDF22. Defaults to Offer ID.

Response (200 OK)

{
  "tsin_id": 0,
  "offer_id": 0,
  "sku": "string",
  "barcode": "string",
  "product_label_number": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "status": "string",
  "title": "string",
  "offer_url": "string",
  "stock_cover": [
    {
      "warehouse_id": 0,
      "stock_cover_days": 0
    }
  ],
  "sales_units": [
    {
      "warehouse_id": 0,
      "sales_units": 0
    }
  ],
  "discount": "string",
  "discount_shown": true,
  "storage_fee_eligible": true,
  "date_created": "string",
  "stock_at_takealot_total": 0,
  "stock_at_takealot": [
    {
      "warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "stock_on_way": [
    {
      "warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "total_stock_on_way": 0,
  "total_stock_cover": 0,
  "catalogue_quality_score": 0
}

Error Responses

403 Forbidden 
{ "message": "string" }
404 Not Found 
{ "message": "string" }
500 Server Error 
{ "message": "string" }
GET /v2/offers/offer

Get an offer (v2)

Retrieve information about an individual offer by providing an identifier for the offer

Parameters

NameInTypeDescription
identifier * query string Either Takealot's Offer ID, the Barcode or your SKU for the offer. Prepend with ID, Barcode, or SKU. e.g. ID234, BARCODE3223, SKUDF22. Defaults to Offer ID.

Response (200 OK)

{
  "tsin_id": 0,
  "offer_id": 0,
  "sku": "string",
  "barcode": "string",
  "product_label_number": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "status": "string",
  "title": "string",
  "offer_url": "string",
  "stock_cover": [
    {
      "warehouse_id": 0,
      "stock_cover_days": 0
    }
  ],
  "sales_units": [
    {
      "warehouse_id": 0,
      "sales_units": 0
    }
  ],
  "discount": "string",
  "discount_shown": true,
  "storage_fee_eligible": true,
  "date_created": "string",
  "stock_at_takealot_total": 0,
  "stock_at_takealot": [
    {
      "warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "stock_on_way": [
    {
      "warehouse": {
        "warehouse_id": 0,
        "name": "string"
      },
      "quantity_available": 0
    }
  ],
  "total_stock_on_way": 0,
  "total_stock_cover": 0,
  "catalogue_quality_score": 0
}

Update an offer

PATCH /v2/offers/offer/{identifier}

Update an offer (v2)

Update an offer by providing an identifier for the offer

Parameters

NameInTypeDescription
identifier * path string Either Takealot's Offer ID, the Barcode or your SKU for the offer. Prepend with ID, BARCODE, or SKU. e.g. ID234, BARCODE3223, SKUDF22. Defaults to Offer ID.
offer * body object See Request Body Schema below

Request Body Schema

{
  "sku": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse_id": 0,
      "quantity": 0
    }
  ],
  "status_action": "Disable"
}

Response (200 OK)

{
  "offer": {
    "tsin_id": 0,
    "offer_id": 0,
    "sku": "string",
    "barcode": "string",
    "product_label_number": "string",
    "selling_price": 0,
    "rrp": 0,
    "leadtime_days": 0,
    "leadtime_stock": [
      {
        "merchant_warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "status": "string",
    "title": "string",
    "offer_url": "string",
    "stock_cover": [
      {
        "warehouse_id": 0,
        "stock_cover_days": 0
      }
    ],
    "sales_units": [
      {
        "warehouse_id": 0,
        "sales_units": 0
      }
    ],
    "discount": "string",
    "discount_shown": true,
    "storage_fee_eligible": true,
    "date_created": "string",
    "stock_at_takealot_total": 0,
    "stock_at_takealot": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "stock_on_way": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "total_stock_on_way": 0,
    "total_stock_cover": 0,
    "catalogue_quality_score": 0
  },
  "validation_errors": [
    {
      "message": "string",
      "code": "string"
    }
  ]
}
PATCH /v2/offers/offer

Update an offer by providing an identifier for the offer

Parameters

NameInTypeDescription
identifier * query string Either Takealot's Offer ID, the Barcode or your SKU for the offer. Prepend with ID, BARCODE, or SKU. e.g. ID234, BARCODE3223, SKUDF22. Defaults to Offer ID.
offer * body object See Request Body Schema below

Request Body Schema

{
  "sku": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse_id": 0,
      "quantity": 0
    }
  ],
  "status_action": "Disable"
}

Response (200 OK)

{
  "offer": {
    "tsin_id": 0,
    "offer_id": 0,
    "sku": "string",
    "barcode": "string",
    "product_label_number": "string",
    "selling_price": 0,
    "rrp": 0,
    "leadtime_days": 0,
    "leadtime_stock": [
      {
        "merchant_warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "status": "string",
    "title": "string",
    "offer_url": "string",
    "stock_cover": [
      {
        "warehouse_id": 0,
        "stock_cover_days": 0
      }
    ],
    "sales_units": [
      {
        "warehouse_id": 0,
        "sales_units": 0
      }
    ],
    "discount": "string",
    "discount_shown": true,
    "storage_fee_eligible": true,
    "date_created": "string",
    "stock_at_takealot_total": 0,
    "stock_at_takealot": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "stock_on_way": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "total_stock_on_way": 0,
    "total_stock_cover": 0,
    "catalogue_quality_score": 0
  },
  "validation_errors": [
    {
      "message": "string",
      "code": "string"
    }
  ]
}
POST /v2/offers/offer/{identifier}

Create an offer by providing the variant's Barcode

Parameters

NameInTypeDescription
identifier * path string The Barcode for the variant to create an offer against. It is not required to prepend BARCODE.
offer * body object See Request Body Schema below

Request Body Schema

{
  "sku": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse_id": 0,
      "quantity": 0
    }
  ]
}

Response (200 OK)

{
  "offer": {
    "tsin_id": 0,
    "offer_id": 0,
    "sku": "string",
    "barcode": "string",
    "product_label_number": "string",
    "selling_price": 0,
    "rrp": 0,
    "leadtime_days": 0,
    "leadtime_stock": [
      {
        "merchant_warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "status": "string",
    "title": "string",
    "offer_url": "string",
    "stock_cover": [
      {
        "warehouse_id": 0,
        "stock_cover_days": 0
      }
    ],
    "sales_units": [
      {
        "warehouse_id": 0,
        "sales_units": 0
      }
    ],
    "discount": "string",
    "discount_shown": true,
    "storage_fee_eligible": true,
    "date_created": "string",
    "stock_at_takealot_total": 0,
    "stock_at_takealot": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "stock_on_way": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "total_stock_on_way": 0,
    "total_stock_cover": 0,
    "catalogue_quality_score": 0
  },
  "validation_errors": [
    {
      "message": "string",
      "code": "string"
    }
  ]
}
POST /v2/offers/offer

Create an offer by providing the variant's Barcode

Parameters

NameInTypeDescription
identifier * query string The Barcode for the variant to create an offer against. It is not required to prepend BARCODE.
offer * body object See Request Body Schema below

Request Body Schema

{
  "sku": "string",
  "selling_price": 0,
  "rrp": 0,
  "leadtime_days": 0,
  "leadtime_stock": [
    {
      "merchant_warehouse_id": 0,
      "quantity": 0
    }
  ]
}

Response (200 OK)

{
  "offer": {
    "tsin_id": 0,
    "offer_id": 0,
    "sku": "string",
    "barcode": "string",
    "product_label_number": "string",
    "selling_price": 0,
    "rrp": 0,
    "leadtime_days": 0,
    "leadtime_stock": [
      {
        "merchant_warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "status": "string",
    "title": "string",
    "offer_url": "string",
    "stock_cover": [
      {
        "warehouse_id": 0,
        "stock_cover_days": 0
      }
    ],
    "sales_units": [
      {
        "warehouse_id": 0,
        "sales_units": 0
      }
    ],
    "discount": "string",
    "discount_shown": true,
    "storage_fee_eligible": true,
    "date_created": "string",
    "stock_at_takealot_total": 0,
    "stock_at_takealot": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "stock_on_way": [
      {
        "warehouse": {
          "warehouse_id": 0,
          "name": "string"
        },
        "quantity_available": 0
      }
    ],
    "total_stock_on_way": 0,
    "total_stock_cover": 0,
    "catalogue_quality_score": 0
  },
  "validation_errors": [
    {
      "message": "string",
      "code": "string"
    }
  ]
}
POST /v2/offers/batch

Create or update multiple offers by submitting a batch. Please note there is a 10k size limit - batches larger than this limit will be rejected.

Parameters

NameInTypeDescription
offers * body array[object] See Request Body Schema below

Request Body Schema

[
  {
    "offer_id": 0,
    "sku": "string",
    "barcode": "string",
    "selling_price": 0,
    "rrp": 0,
    "leadtime_days": 0,
    "leadtime_stock": [
      {
        "merchant_warehouse_id": 0,
        "quantity": 0
      }
    ],
    "status_action": "Disable"
  }
]

Response (200 OK)

{
  "batch_id": "string",
  "status": {
    "description": "string",
    "id": 0
  },
  "result": [
    {
      "validation_errors": [
        {
          "message": "string",
          "code": "string"
        }
      ],
      "offer": {
        "selling_price": 0,
        "rrp": 0,
        "leadtime_days": 0,
        "leadtime_stock": [
          {
            "merchant_warehouse": {
              "warehouse_id": 0,
              "name": "string"
            },
            "quantity_available": 0
          }
        ],
        "stock_at_takealot": [
          {
            "warehouse": {
              "warehouse_id": 0,
              "name": "string"
            },
            "quantity_available": 0
          }
        ],
        "status": "string",
        "sku": "string",
        "offer_id": 0
      }
    }
  ]
}
GET /v2/offers/batch/{batch_id}

Query the current status of a batch, and view results if they are available

Parameters

NameInTypeDescription
batch_id * path string The ID of the batch you have submitted, provided to you by Takealot

Response (200 OK)

{
  "batch_id": "string",
  "status": {
    "description": "string",
    "id": 0
  },
  "result": [
    {
      "validation_errors": [
        {
          "message": "string",
          "code": "string"
        }
      ],
      "offer": {
        "selling_price": 0,
        "rrp": 0,
        "leadtime_days": 0,
        "leadtime_stock": [
          {
            "merchant_warehouse": {
              "warehouse_id": 0,
              "name": "string"
            },
            "quantity_available": 0
          }
        ],
        "stock_at_takealot": [
          {
            "warehouse": {
              "warehouse_id": 0,
              "name": "string"
            },
            "quantity_available": 0
          }
        ],
        "status": "string",
        "sku": "string",
        "offer_id": 0
      }
    }
  ]
}
GET /{version}/offers/stock_counts

Retrieve the total number of your offers that have stock at Takealot, as well as the number of offers that have an unbalanced stock level at Takealot

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)

Response (200 OK)

{
  "count": 0
}
GET /{version}/offers/stock_health_stats

Retrieve your stock health statistics

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)

Response (200 OK)

{
  "storage_fee_enabled_offer_count": 0
}
GET /{version}/sales

Get sales based on filters passed through

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)
filters query array[string] A list of search parameters (supported fields are start_date, end_date, sku, product_title, tsin, dc, customer_dc, sale_status, po_number, order_id, promotion) e.g. ?filters=sku:foo;title:bar
page_number query integer The page number to retrieve (starting at 1)
page_size query integer The number of sales per page. Limited to 100.

Response (200 OK)

{
  "page_summary": {
    "page_size": 0,
    "page_number": 0,
    "total": 0
  },
  "sales": [
    {
      "shipment_id": 0,
      "shipment_state_id": 0,
      "po_number": 0,
      "shipment_name": "string",
      "offer_id": 0,
      "product_title": "string",
      "takealot_url_mobi": "string",
      "sku": "string",
      "tsin": 0,
      "order_id": 0,
      "order_item_id": 0,
      "quantity": 0,
      "selling_price": 0,
      "dc": "string",
      "customer_dc": "string",
      "order_date": "string",
      "sale_status": true,
      "promotion": true,
      "customer": "string",
      "stock_source_region": "string"
    }
  ]
}
GET /{version}/sales/summary

Get sales summary

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)

Response (200 OK)

{
  "sales_summary": [
    {
      "date_range": "string",
      "total": 0,
      "quantity": 0
    }
  ]
}
GET /{version}/sales/orders

Get sales orders based on filters passed through

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)
start_date * query string The start date for filtering orders
end_date * query string The end date for filtering orders
sku query string The SKU for filtering orders
product_title query string The product title for filtering orders
tsin query integer The TSIN for filtering orders
order_id query integer The order ID for filtering orders
page_number query integer The page number to retrieve (starting at 1)
page_size query integer The number of sales per page. Limited to 100.

Response (200 OK)

{
  "page_summary": {
    "page_size": 0,
    "page_number": 0,
    "total": 0
  },
  "sales": [
    {
      "shipment_id": 0,
      "shipment_state_id": 0,
      "po_number": 0,
      "shipment_name": "string",
      "offer_id": 0,
      "product_title": "string",
      "takealot_url_mobi": "string",
      "sku": "string",
      "tsin": 0,
      "order_id": 0,
      "order_item_id": 0,
      "quantity": 0,
      "selling_price": 0,
      "dc": "string",
      "customer_dc": "string",
      "order_date": "string",
      "sale_status": true,
      "promotion": true,
      "customer": "string",
      "stock_source_region": "string"
    }
  ]
}
GET /{version}/sales/orders/{order_id}/customer_invoices

Get invoices or credit notes for a specific order

Parameters

NameInTypeDescription
version * path string The major version of the API, prepended with a v (e.g. v1)
order_id * path integer The start date for filtering orders

Response (200 OK)

{
  "documents": [
    {
      "document_id": 0,
      "document_date": "string",
      "document_type": "string",
      "document_reason": "string",
      "file_name": "string",
      "downloadable": true
    }
  ]
}

Common Error Schema

When a default or generic error occurs, the API may return:

{
  "fields": "string",
  "message": "string",
  "status": 0
}