API docs by Redocly

Takealot Marketplace API (1.0.0)

Download OpenAPI specification:

A service for merchants to integrate with Takealot seller information.

This API allows merchants to manage their seller information, offers, orders, returns, shipments, and more on the Takealot marketplace platform.

Overview

Authorisation

All endpoints that deal with seller-specific information require an API key to be provided in the X-API-Key header.

Obtain an API key:

  • Register for a Takealot Seller account if you don't already have one.

  • Log in as the account owner and navigate to the API Access section in the Seller Portal.

  • Generate a new API key and copy it for use in your API requests.

Currently, only one API key can be active at a time per seller account. If you generate a new API key, the previous one will be deactivated.

The API key has access to all the endpoints in this API, but only for the seller account it is associated with. There are no separate permissions or scopes for different endpoints.

Collection queries

Collection endpoints support pagination and field selection to help manage large datasets and optimize response sizes.

  • Use the fields query parameter to specify which fields you want included in the response. This can help reduce the size of the response and improve performance by only returning the data you need.

  • Use the expands query parameter to include related resources in the response. This allows you to retrieve associated data in a single request, reducing the need for multiple round-trips to the API.

  • Use the limit query parameter to specify the maximum number of items to return in a single response. If there are more items available than the specified limit, a continuation_token will be included in the response that can be used to retrieve the next page of results.

  • Use the include_count query parameter set to true if you want the response to include a count field indicating the total number of items in the collection that match the given query parameters. Note that including a count may impact performance, especially for large datasets, as it may require an additional query to determine the total count.

Collection responses

Collection reponses generally return the following:

  • A list of items in a field named items.

  • A limit field indicating the maximum number of items that could be returned in the current response. This is determined by the limit query parameter provided in the request, or a default value if the parameter is not provided.

  • A count field indicating the total number of items in the collection with the given query parameters. This will only be included if the include_count query parameter is set to true.

  • A continuation_token field if there are more items in the collection that were not included in the current response. This token can be used to retrieve the next page of results. See the Pagination section below for details.

Pagination

If the current result set is large and does not fit into the current response, the response will include a continuation_token in the body.

Use this token in the continuation_token query parameter to retrieve the next page of results.

Any other parameters provided together with a continuation token will be ignored.

When a continuation token is provided in the request, the response will NOT include a count.

When the end of the collection is reached, the continuation token will be omitted from the response.

Single item queries and responses

Single item endpoints generally return the item directly in the response body, without an additional nesting field. For example, a GET request to /offers/{offer_id} will return the offer object directly in the response body.

if the requested item is not found, the API will return a 404 Not Found status code with an empty response body.

The same fields and expands query parameters that are available for collection endpoints can also be used with single item endpoints to specify which fields and related resources should be included in the response.

General

General endpoints.

Documentation

Get the documentation for the API.

This endpoint serves the HTML content of the API documentation, generated using ReDoc. The documentation provides details about the available endpoints, request/response formats, and other relevant information for developers using the API.

NOTE: This endpoint is intended for human consumption and is not designed for programmatic access.

Responses

API Status

Check the status of the API to ensure it is reachable and operational.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Offers

The offers endpoints.

List Offers

List Offers.

Authorizations:
api_key
query Parameters
offer_id
integer <int32> (OfferID) >= 1
Example: offer_id=1234567890

Takealot offer ID

offer_id__in
Array of integers <int32> (OfferID) [ items <int32 > >= 1 ]
Example: offer_id__in=1234567&offer_id__in=1234568&offer_id__in=1234569

Filter by offers with these IDs.

status
string
Enum: "buyable" "not_buyable" "disabled_by_seller" "disabled_by_takealot"
Example: status=buyable

Only include offers with this status.

offer_id__gt
integer <int32> (OfferID) >= 1
Example: offer_id__gt=1000000

Only include offers with IDs greater than this value.

offer_id__lt
integer <int32> (OfferID) >= 1
Example: offer_id__lt=2000000

Only include offers with IDs less than this value.

sku
string
Example: sku=SKU-ABC123

Only include offers with this SKU.

barcode
string
Example: barcode=MPTALX12345678-9

Only include offers with this barcode.

fields
Array of strings
Items Enum: "offer_id" "tsin_id" "sku" "barcode" "product_label" "selling_price" "rrp" "minimum_leadtime_days" "status" "title" "discount_percentage" "storage_fee_eligible" "created_at" "updated_at" "affected_by_vacation" "disabled_by_seller" "disabled_by_takealot" "conversion_percentage_30_days" "conversion_percentage_previous_30_days" "page_views_30_days" "quantity_returned_30_days" "condition" "image_url" "productline_id" "width_cm" "length_cm" "height_cm" "weight_grams" "is_conveyable" "benchmark_price" "total_wishlist" "wishlist_30_days" "listing_quality"
Example: fields=offer_id&fields=sku&fields=selling_price&fields=status&fields=title

Return only these fields.

expands
Array of strings
Items Enum: "seller_warehouse_stock" "offer_charges" "takealot_warehouse_stock" "replenishment_blocks"
Example: expands=seller_warehouse_stock&expands=takealot_warehouse_stock

Expand the response with related entities.

Note on replenishment_blocks: Including this enum will only return a response if the offer is currently subject to an explicit, full replenishment block. It does not return data regarding replenishment limits (including instances where the limit is 0, which acts as a block) or replenishment allows. If the offer is not fully blocked, no replenishment data will be returned.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Limit the number of results returned. Default is 100, maximum is 1000.

continuation_token
string >= 1
Example: continuation_token=eyJvZmZzZXQiOiAxMDB9

Continuation token to get the next page of results. Obtained from a previous response.

order_by
string >= 1
Default: "offer_id"
Enum: "offer_id" "-offer_id"
Example: order_by=-offer_id

Order the results by these fields. Prefix with '-' for descending order.

include_count
boolean
Default: false
Example: include_count=true

Include a count of total items in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 150,
  • "limit": 100,
  • "continuation_token": "eyJvZmZzZXQiOiAxMDB9"
}

Create offer

Create a new offer.

Authorizations:
api_key
query Parameters
fields
Array of strings
Items Enum: "offer_id" "tsin_id" "sku" "barcode" "product_label" "selling_price" "rrp" "minimum_leadtime_days" "status" "title" "discount_percentage" "storage_fee_eligible" "created_at" "updated_at" "affected_by_vacation" "disabled_by_seller" "disabled_by_takealot" "conversion_percentage_30_days" "conversion_percentage_previous_30_days" "page_views_30_days" "quantity_returned_30_days" "condition" "image_url" "productline_id" "width_cm" "length_cm" "height_cm" "weight_grams" "is_conveyable" "benchmark_price" "total_wishlist" "wishlist_30_days" "listing_quality"
Example: fields=offer_id&fields=sku&fields=selling_price&fields=status&fields=title

Return only these fields.

expands
Array of strings
Items Enum: "seller_warehouse_stock" "offer_charges" "takealot_warehouse_stock" "replenishment_blocks"
Example: expands=seller_warehouse_stock&expands=takealot_warehouse_stock

Expand the response with related entities.

Note on replenishment_blocks: Including this enum will only return a response if the offer is currently subject to an explicit, full replenishment block. It does not return data regarding replenishment limits (including instances where the limit is 0, which acts as a block) or replenishment allows. If the offer is not fully blocked, no replenishment data will be returned.

Request Body schema: application/json
required

Request body for creating an offer.

non-empty
barcode
string non-empty

Barcode for the offer (provided by the merchant)

sku
string (SKURequestBody) [ 1 .. 255 ] characters ^[a-zA-Z0-9-_/.]+$

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

minimum_leadtime_days
integer

The leadtime in days for the offer to be shipped to a Takealot facility when shipped from the seller's warehouse.

selling_price
integer <int32> (SellingPriceRequestBody) >= 1

Selling Price in South African Rand.

rrp
integer <int32> (RRPRequestBody) >= 1

RRP (Recommended Retail Price) in South African Rand.

Array of objects

Stock levels in the seller's warehouses.

Responses

Request samples

Content type
application/json
{
  • "barcode": "MPTALX12345678-9",
  • "sku": "SKU-ABC123",
  • "minimum_leadtime_days": 5,
  • "selling_price": 345,
  • "rrp": 399,
  • "seller_warehouse_stock": [
    ]
}

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

get offer by ID

Get an offer by its ID.

Authorizations:
api_key
path Parameters
offer_id
required
integer <int32> (OfferID) >= 1
Example: 1234567890

Takealot offer ID

query Parameters
fields
Array of strings
Items Enum: "offer_id" "tsin_id" "sku" "barcode" "product_label" "selling_price" "rrp" "minimum_leadtime_days" "status" "title" "discount_percentage" "storage_fee_eligible" "created_at" "updated_at" "affected_by_vacation" "disabled_by_seller" "disabled_by_takealot" "conversion_percentage_30_days" "conversion_percentage_previous_30_days" "page_views_30_days" "quantity_returned_30_days" "condition" "image_url" "productline_id" "width_cm" "length_cm" "height_cm" "weight_grams" "is_conveyable" "benchmark_price" "total_wishlist" "wishlist_30_days" "listing_quality"
Example: fields=offer_id&fields=sku&fields=selling_price&fields=status&fields=title

Return only these fields.

expands
Array of strings
Items Enum: "seller_warehouse_stock" "offer_charges" "takealot_warehouse_stock" "replenishment_blocks"
Example: expands=seller_warehouse_stock&expands=takealot_warehouse_stock

Expand the response with related entities.

Note on replenishment_blocks: Including this enum will only return a response if the offer is currently subject to an explicit, full replenishment block. It does not return data regarding replenishment limits (including instances where the limit is 0, which acts as a block) or replenishment allows. If the offer is not fully blocked, no replenishment data will be returned.

Responses

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

update offer by ID

Update an offer by its ID.

Authorizations:
api_key
path Parameters
offer_id
required
integer <int32> (OfferID) >= 1
Example: 1234567890

Takealot offer ID

Request Body schema: application/json
required

Request body for updating an offer.

non-empty
sku
string (SKURequestBody) [ 1 .. 255 ] characters ^[a-zA-Z0-9-_/.]+$

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

minimum_leadtime_days
integer

The leadtime in days for the offer to be shipped to a Takealot facility when shipped from the seller's warehouse.

selling_price
integer <int32> (SellingPriceRequestBody) >= 1

Selling Price in South African Rand.

rrp
integer <int32> (RRPRequestBody) >= 1

RRP (Recommended Retail Price) in South African Rand.

Array of objects

Stock levels in the seller's warehouses.

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU-ABC123",
  • "minimum_leadtime_days": 5,
  • "selling_price": 345,
  • "rrp": 399,
  • "seller_warehouse_stock": [
    ]
}

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

get offer by sku

Get an offer by its sku.

Authorizations:
api_key
path Parameters
sku
required
string non-empty
Example: SKU-ABC123

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

query Parameters
fields
Array of strings
Items Enum: "offer_id" "tsin_id" "sku" "barcode" "product_label" "selling_price" "rrp" "minimum_leadtime_days" "status" "title" "discount_percentage" "storage_fee_eligible" "created_at" "updated_at" "affected_by_vacation" "disabled_by_seller" "disabled_by_takealot" "conversion_percentage_30_days" "conversion_percentage_previous_30_days" "page_views_30_days" "quantity_returned_30_days" "condition" "image_url" "productline_id" "width_cm" "length_cm" "height_cm" "weight_grams" "is_conveyable" "benchmark_price" "total_wishlist" "wishlist_30_days" "listing_quality"
Example: fields=offer_id&fields=sku&fields=selling_price&fields=status&fields=title

Return only these fields.

expands
Array of strings
Items Enum: "seller_warehouse_stock" "offer_charges" "takealot_warehouse_stock" "replenishment_blocks"
Example: expands=seller_warehouse_stock&expands=takealot_warehouse_stock

Expand the response with related entities.

Note on replenishment_blocks: Including this enum will only return a response if the offer is currently subject to an explicit, full replenishment block. It does not return data regarding replenishment limits (including instances where the limit is 0, which acts as a block) or replenishment allows. If the offer is not fully blocked, no replenishment data will be returned.

Responses

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

update offer by sku

Update an offer by its sku.

Authorizations:
api_key
path Parameters
sku
required
string non-empty
Example: SKU-ABC123

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

Request Body schema: application/json
required

Request body for updating an offer.

non-empty
sku
string (SKURequestBody) [ 1 .. 255 ] characters ^[a-zA-Z0-9-_/.]+$

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

minimum_leadtime_days
integer

The leadtime in days for the offer to be shipped to a Takealot facility when shipped from the seller's warehouse.

selling_price
integer <int32> (SellingPriceRequestBody) >= 1

Selling Price in South African Rand.

rrp
integer <int32> (RRPRequestBody) >= 1

RRP (Recommended Retail Price) in South African Rand.

Array of objects

Stock levels in the seller's warehouses.

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU-ABC123",
  • "minimum_leadtime_days": 5,
  • "selling_price": 345,
  • "rrp": 399,
  • "seller_warehouse_stock": [
    ]
}

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

get offer by barcode

Get an offer by its barcode.

Authorizations:
api_key
path Parameters
barcode
required
string non-empty
Example: MPTALX12345678-9

Barcode for the offer (provided by the merchant)

query Parameters
fields
Array of strings
Items Enum: "offer_id" "tsin_id" "sku" "barcode" "product_label" "selling_price" "rrp" "minimum_leadtime_days" "status" "title" "discount_percentage" "storage_fee_eligible" "created_at" "updated_at" "affected_by_vacation" "disabled_by_seller" "disabled_by_takealot" "conversion_percentage_30_days" "conversion_percentage_previous_30_days" "page_views_30_days" "quantity_returned_30_days" "condition" "image_url" "productline_id" "width_cm" "length_cm" "height_cm" "weight_grams" "is_conveyable" "benchmark_price" "total_wishlist" "wishlist_30_days" "listing_quality"
Example: fields=offer_id&fields=sku&fields=selling_price&fields=status&fields=title

Return only these fields.

expands
Array of strings
Items Enum: "seller_warehouse_stock" "offer_charges" "takealot_warehouse_stock" "replenishment_blocks"
Example: expands=seller_warehouse_stock&expands=takealot_warehouse_stock

Expand the response with related entities.

Note on replenishment_blocks: Including this enum will only return a response if the offer is currently subject to an explicit, full replenishment block. It does not return data regarding replenishment limits (including instances where the limit is 0, which acts as a block) or replenishment allows. If the offer is not fully blocked, no replenishment data will be returned.

Responses

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

update offer by barcode

Update an offer by its barcode.

Authorizations:
api_key
path Parameters
barcode
required
string non-empty
Example: MPTALX12345678-9

Barcode for the offer (provided by the merchant)

Request Body schema: application/json
required

Request body for updating an offer.

non-empty
sku
string (SKURequestBody) [ 1 .. 255 ] characters ^[a-zA-Z0-9-_/.]+$

SKU (Stock Keeping Unit) for the offer (provided by the merchant)

minimum_leadtime_days
integer

The leadtime in days for the offer to be shipped to a Takealot facility when shipped from the seller's warehouse.

selling_price
integer <int32> (SellingPriceRequestBody) >= 1

Selling Price in South African Rand.

rrp
integer <int32> (RRPRequestBody) >= 1

RRP (Recommended Retail Price) in South African Rand.

Array of objects

Stock levels in the seller's warehouses.

Responses

Request samples

Content type
application/json
{
  • "sku": "SKU-ABC123",
  • "minimum_leadtime_days": 5,
  • "selling_price": 345,
  • "rrp": 399,
  • "seller_warehouse_stock": [
    ]
}

Response samples

Content type
application/json
{
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "sku": "SKU-ABC123",
  • "barcode": "MPTALX12345678-9",
  • "product_label": "9902198765432",
  • "selling_price": 345,
  • "rrp": 399,
  • "minimum_leadtime_days": 3,
  • "status": "buyable",
  • "title": "Apple iPhone 13 Pro Max (256GB) - Silver",
  • "discount_percentage": 15.5,
  • "storage_fee_eligible": true,
  • "created_at": "2024-01-15T12:34:56+02:00",
  • "updated_at": "2025-01-15T12:34:56+02:00",
  • "affected_by_vacation": false,
  • "disabled_by_seller": false,
  • "disabled_by_takealot": false,
  • "conversion_percentage_30_days": 12.5,
  • "conversion_percentage_previous_30_days": 10.2,
  • "page_views_30_days": 1500,
  • "quantity_returned_30_days": 10,
  • "condition": "New",
  • "image_url": "https://images.example.com/images/sellers/12345/offer/67890/image.jpg",
  • "productline_id": 98765,
  • "width_cm": 15.5,
  • "length_cm": 25.1,
  • "height_cm": 10.2,
  • "weight_grams": 345.8,
  • "is_conveyable": true,
  • "benchmark_price": 1499,
  • "total_wishlist": 250,
  • "wishlist_30_days": 159,
  • "listing_quality": 85,
  • "seller_warehouse_stock": [
    ],
  • "takealot_warehouse_stock": [
    ],
  • "offer_charges": [
    ],
  • "replenishment_blocks": [
    ]
}

create offer batch

Create an offer batch .

Authorizations:
api_key
Request Body schema: application/json
required

Request body for creating an offer batch.

non-empty
Array of objects <= 10000 items

Responses

Request samples

Content type
application/json
{
  • "offers": [
    ]
}

Response samples

Content type
application/json
{
  • "batch_id": 0,
  • "status": "string"
}

get offer batch by ID

Get an offer batch by its ID.

Authorizations:
api_key
path Parameters
batch_id
required
integer
Example: 98765

The unique identifier of the offer batch.

Responses

Response samples

Content type
application/json
{
  • "batch_id": 98765,
  • "status": "completed",
  • "results": [ ]
}

Sales

The sales endpoints.

List Sales

List all your sales.

Authorizations:
api_key
query Parameters
order_id
integer >= 1
Example: order_id=9876543

Filter sales by order ID.

order_date__lte
string <date>
Example: order_date__lte=2025-12-31

Paired with order_date__gte, together forming an inclusive daterange for order_date, in SAST.

order_date__gte
string <date>
Example: order_date__gte=2025-01-01

Paired with order_date__lte, together forming an inclusive daterange for order_date, in SAST.

stock_source_region
string
Enum: "cpt" "CPT" "jhb" "JHB" "dbn" "DBN"
Example: stock_source_region=JHB

Filter sales by the region from which the stock was sourced.

limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=50

The number of sales per page.

fields
Array of strings
Items Enum: "order_item_id" "order_id" "order_date" "sale_status" "offer_id" "tsin_id" "sku" "selling_price" "quantity" "success_fee" "fulfillment_fee" "courier_collection_fee" "total_fees" "stock_transfer_fee" "sales_region" "stock_source_region"
Example: fields=order_id&fields=order_date&fields=sale_status&fields=selling_price&fields=quantity

Return only these fields.

continuation_token
string >= 1
Example: continuation_token=eyJvZmZzZXQiOiAxMDB9

Continuation token to get the next page of results. Obtained from a previous response.

include_count
boolean
Default: false
Example: include_count=true

Include a count of total items in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 150,
  • "limit": 100,
  • "continuation_token": "eyJvZmZzZXQiOiAxMDB9"
}

Transactions

The transactions endpoints.

List Transactions

List transactions.

This endpoint allows you to retrieve a list of transactions based on various filters.

The transactions are returned in descending order of their transaction_id, meaning the most recent transactions will be listed first.

Note: The maximum allowable date range is 180 days, and the default will show the last 30 days.

Authorizations:
api_key
query Parameters
transaction_type__in
Array of strings (TransactionTypeEnum) [ items >= 1 ]
Items Enum Description
charge-subscription-fee

A monthly subscription fee charge

charge-fulfilment-fee

A fulfilment fee associated with a customer order

charge-storage-fee

A storage fee charged for stock in warehouse

charge-success-fee

A success fee associated with a customer order

reversal-success-fee

A success fee reversal for a return/cancellation

payment-customer-order

A customer order payment

reversal-customer-order

A reversal for a customer order payment

disbursement-disbursement

A disbursement transaction

reversal-disbursement

A disbursement transaction reversal

payment-eft-payment

An eft payment

charge-manual

A manual fee charge

disbursement-manual

A manual disbursement

reversal-manual

A manual reversal of a transaction

payment-manual

A manual payment

payment-debit-order

A debit order payment

reversal-debit-order

A debit order reversal

payment-storage-fee-rebate

A storage fee rebate

reversal-storage-fee-rebate-reversal

A storage fee rebate reversal

charge-order-cancellation-penalty

An order cancellation penalty

charge-courier-collection-fee

A courier collection fee associated with an order

charge-removal-order

A removal order fee

charge-stock-transfer-fee

A stock transfer fee associated with an order

charge-ad-credit-purchase

A sponsored ad credit purchase

reversal-fulfilment-fee

A reversal of a fulfilment fee

reversal-courier-collection-fee

A reversal of a courier collection fee

reversal-removal-order-fee-reversal

A reversal of a removal order fee

payment-stock-loss-payment

A stock loss payment

reversal-stock-loss-reversal

A stock loss payment reversal

charge-stock-loss-success-fee

A stock loss success fee charge

reversal-stock-loss-success-fee-reversal

A reversal of a stock loss success fee charge

charge-stock-loss-fulfilment-fee

A stock loss fulfillment fee charge

reversal-stock-loss-fulfilment-fee-reversal

A reversal of a stock loss fulfillment fee charge

payment-return-dispute-payment

A return dispute payment

charge-removal-order-fee

A removal order fee

charge-takealot-removal-order-fee

A Takealot removal order fee

charge-returns-removal-order-fee

A returns removal order fee

funding-repayment-funding-repayment-seller-capital

A Seller Capital funding repayment

Example: transaction_type__in=charge-success-fee&transaction_type__in=payment-customer-order

Return only transactions of these types.

created_at__gte
string <date-time>
Example: created_at__gte=2025-01-01T00:00:00+02:00

Default: now - 30 days

The transaction created_at must be greater than or equal to this value. (The start date for the query).

Must not be in the future.

created_at__lte
string <date-time>
Example: created_at__lte=2025-01-31T23:59:59+02:00

Default: now

The transaction created_at must be less than or equal to this value. (The end date for the query).

Must not be in the future.

limit
integer [ 1 .. 100 ]
Default: 20
Example: limit=50

The number of transactions per page.

fields
Array of strings
Items Enum: "transaction_id" "transaction_type" "amount_incl_vat" "vat_multiplier" "created_at"
Example: fields=transaction_id&fields=transaction_type&fields=amount_incl_vat&fields=created_at

Return only these fields.

expands
Array of strings
Items Value: "references"
Example: expands=references

Expand the response with related entities.

continuation_token
string >= 1
Example: continuation_token=eyJvZmZzZXQiOiAxMDB9

Continuation token to get the next page of results. Obtained from a previous response.

include_count
boolean
Default: false
Example: include_count=true

Include a count of total items in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 150,
  • "limit": 100,
  • "continuation_token": "eyJvZmZzZXQiOiAxMDB9"
}

Get disbursement information

Retrieves disbursement information for sellers

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "balances": {
    }
}

Shipments

The shipments endpoints.

List Shipments

List shipments.

Authorizations:
api_key
query Parameters
shipment_id
integer
Example: shipment_id=12345

Filter shipments by shipment ID.

shipment_id__lt
integer
Example: shipment_id__lt=20000

Filter shipments with shipment ID less than this value.

shipment_id__gt
integer
Example: shipment_id__gt=10000

Filter shipments with shipment ID greater than this value.

shipment_id__in
Array of integers
Example: shipment_id__in=12345&shipment_id__in=12346&shipment_id__in=12347

Filter shipments with shipment IDs in this list.

shipment_type__in
Array of strings (ShipmentTypeEnum)
Items Enum: "customer_order" "replenishment" "mixed"
Example: shipment_type__in=replenishment&shipment_type__in=customer_order

Filter shipments with shipment types in this list.

shipped
boolean
Example: shipped=true

Filter shipments by shipped status.

cancelled
boolean

Filter shipments by cancelled status.

order_by
string >= 1
Default: "-shipment_id"
Enum: "shipment_id" "-shipment_id"
Example: order_by=-shipment_id

Order the results by these fields. Prefix with '-' for descending order.

fields
Array of strings
Items Enum: "shipment_id" "reference" "destination_region" "shipped" "archived" "purchase_order_number" "cancelled" "due_date" "created_at" "purchase_order_state" "shipment_type" "due_date_last_modified" "date_unloaded" "destination_facility_id" "tracking_info"
Example: fields=shipment_id&fields=reference&fields=destination_region&fields=shipped&fields=due_date&fields=created_at

Return only these fields.

expands
Array of strings
Items Value: "shipment_items"
Example: expands=shipment_items

Expand the response with related entities.

limit
integer [ 1 .. 1000 ]
Default: 100
Example: limit=50

Limit the number of results returned. Default is 100, maximum is 1000.

include_count
boolean
Default: false
Example: include_count=true

Include a count of total items in the response.

continuation_token
string >= 1
Example: continuation_token=eyJvZmZzZXQiOiAxMDB9

Continuation token to get the next page of results. Obtained from a previous response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 150,
  • "limit": 100,
  • "continuation_token": "eyJvZmZzZXQiOiAxMDB9"
}

Get a Shipment

Get a shipment by shipment ID.

Authorizations:
api_key
path Parameters
shipment_id
required
integer
Example: 12345

The unique identifier of the shipment.

query Parameters
fields
Array of strings
Items Enum: "shipment_id" "reference" "destination_region" "shipped" "archived" "purchase_order_number" "cancelled" "due_date" "created_at" "purchase_order_state" "shipment_type" "due_date_last_modified" "date_unloaded" "destination_facility_id" "tracking_info"
Example: fields=shipment_id&fields=reference&fields=destination_region&fields=shipped&fields=due_date&fields=created_at

Return only these fields.

expands
Array of strings
Items Value: "shipment_items"
Example: expands=shipment_items

Expand the response with related entities.

Responses

Response samples

Content type
application/json
{
  • "shipment_id": 12345,
  • "reference": "PO-2987543-07/12/2025-JHB-1",
  • "destination_region": "JHB",
  • "shipped": false,
  • "archived": false,
  • "purchase_order_number": 2987543,
  • "cancelled": false,
  • "due_date": "2025-07-15",
  • "created_at": "2025-07-01T10:30:00+02:00",
  • "due_date_last_modified": "2025-06-01T10:30:00+02:00",
  • "date_unloaded": "2025-08-01T10:30:00+02:00",
  • "destination_facility_id": 6,
  • "shipment_type": "replenishment",
  • "purchase_order_state": "shipped",
  • "tracking_info": "Carrier: DHL, Tracking Number: 123456789",
  • "shipment_items": [
    ]
}

Returns

The returns endpoints.

List Returns

List Seller Returns, including related transactions and outcomes.

Authorizations:
api_key
query Parameters
fields
Array of strings
Items Enum: "customer_comment" "offer_id" "order_id" "quantity" "return_region" "return_date" "return_reason" "return_reference_number" "seller_return_id" "sku" "tsin_id"
Example: fields=seller_return_id&fields=order_id&fields=return_date&fields=return_reason

Return only these fields.

expands
Array of strings
Items Enum: "outcomes" "transactions"
Example: expands=outcomes&expands=transactions

Expand the response with related entities.

return_reason__in
Array of strings (ReturnReasonEnum)
Items Enum: "changed_my_mind" "customer_cancellation" "defective_or_damaged" "exception" "exchange_for_a_different_size_colour" "failed_delivery" "not_what_i_ordered"
Example: return_reason__in=defective_or_damaged&return_reason__in=not_what_i_ordered

Only include returns with these reasons.

outcome__in
Array of strings (ReturnOutcomeEnum)
Items Enum: "pending_removal_order" "removal_order" "pending_sellable_stock" "sellable_stock"
Example: outcome__in=sellable_stock&outcome__in=removal_order

Only include returns with these outcomes.

return_region__in
Array of strings (RegionQueryEnum)
Items Enum: "CPT" "JHB" "DBN" "cpt" "jhb" "dbn"
Example: return_region__in=JHB&return_region__in=CPT

List returns processed in these regions.

return_date__gte
string <date>
Example: return_date__gte=2025-01-01

Only returns from this date

return_date__lte
string <date>
Example: return_date__lte=2025-12-31

Only returns until this date

order_id
integer
Example: order_id=9876543

Filter returns by order ID.

return_reference_number
string
Example: return_reference_number=RRN-QBYQ7-E67K

Filter returns by the original customer return reference number (RRN).

sku
string
Example: sku=SKU-ABC123

Filter returns by SKU.

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=25

Limit the number of results returned. Default is 10, maximum is 100.

continuation_token
string >= 1
Example: continuation_token=eyJvZmZzZXQiOiAxMDB9

Continuation token to get the next page of results. Obtained from a previous response.

order_by
string >= 1
Default: "-return_date"
Enum: "return_date" "-return_date"
Example: order_by=-return_date

Order the results by these fields. Prefix with '-' for descending order.

include_count
boolean
Default: false
Example: include_count=true

Include a count of total items in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 150,
  • "limit": 100,
  • "continuation_token": "eyJvZmZzZXQiOiAxMDB9"
}

Get Return by ID

Get a return by Return ID.

Authorizations:
api_key
path Parameters
return_id
required
integer
Example: 9876543

Takealot return ID

query Parameters
fields
Array of strings
Items Enum: "customer_comment" "offer_id" "order_id" "quantity" "return_region" "return_date" "return_reason" "return_reference_number" "seller_return_id" "sku" "tsin_id"
Example: fields=seller_return_id&fields=order_id&fields=return_date&fields=return_reason

Return only these fields.

expands
Array of strings
Items Enum: "outcomes" "transactions"
Example: expands=outcomes&expands=transactions

Expand the response with related entities.

Responses

Response samples

Content type
application/json
{
  • "seller_return_id": 12345,
  • "order_id": 9876543,
  • "offer_id": 123456,
  • "tsin_id": 23456789,
  • "return_reference_number": "RRN-QBYQ7-E67K",
  • "sku": "SKU-ABC123",
  • "return_region": "JHB",
  • "quantity": 1,
  • "return_date": "2024-05-15",
  • "return_reason": "defective_or_damaged",
  • "outcomes": [
    ],
  • "transactions": [
    ],
  • "customer_comment": "The product was defective and did not work as expected."
}

Facilities

The facilities endpoints.

List the enabled regions for facilities

Get the enabled region codes and ids for facilities.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "regions": [
    ]
}

Seller

The seller info endpoints.

Get seller information

Get information about the logged-in seller.

Authorizations:
api_key
query Parameters
fields
Array of strings
Items Enum: "account_owner_account_id" "account_verified" "barcode_exempt" "date_added" "date_terms_accepted" "debit_order_enabled" "debit_order_exempt" "direct_return_procedure" "disable_listing_enabled" "disbursement_enabled" "display_name" "drop_ship_enabled" "force_registration_exempt" "is_international" "is_vat_registered" "leadtime_enabled" "legal_name" "logo" "main_contact_account_id" "on_vacation" "onboarding_exempt" "registration_complete" "replenishment_disabled" "seller_id" "seller_status_id" "terms_accepted" "used_goods_enabled" "uuid"
Example: fields=seller_id&fields=display_name&fields=legal_name&fields=on_vacation

Return only these fields.

expands
Array of strings
Items Enum: "warehouses" "leadtime_details" "vacations" "countries"
Example: expands=warehouses&expands=vacations

Expand the response with related entities.

Responses

Response samples

Content type
application/json
{
  • "seller_id": 12345,
  • "display_name": "Tech Gadgets Store",
  • "legal_name": "Tech Gadgets (Pty) Ltd",
  • "logo": "https://seller-logos.takealot.com/12345/logo.png",
  • "leadtime_enabled": true,
  • "terms_accepted": true,
  • "on_vacation": false,
  • "account_owner_account_id": 54321,
  • "main_contact_account_id": 54322,
  • "disable_listing_enabled": true,
  • "used_goods_enabled": false,
  • "disbursement_enabled": true,
  • "debit_order_enabled": false,
  • "drop_ship_enabled": false,
  • "debit_order_exempt": false,
  • "barcode_exempt": false,
  • "account_verified": true,
  • "force_registration_exempt": false,
  • "direct_return_procedure": "standard",
  • "seller_status_id": 1,
  • "date_added": "2023-06-15",
  • "date_terms_accepted": "2023-06-15",
  • "registration_complete": true,
  • "onboarding_exempt": false,
  • "replenishment_disabled": false,
  • "is_international": false,
  • "is_vat_registered": true,
  • "uuid": "123e4567-e89b-12d3-a456-426614174000",
  • "countries": [
    ],
  • "leadtime_details": [
    ],
  • "warehouses": [
    ],
  • "vacations": [
    ]
}