Takealot Seller Portal Guides

Takealot Seller API

What is an API?

“API” is an acronym for “Application Programming Interface”. An API establishes a common language/interface, which enables two software programs to communicate with each other. An API enables your own software program(s), that you use to manage your ecommerce channels, to send data to and from your Seller Portal account in an automated way.

The benefit of using an API is that it takes away the manual effort required to keep the data between your own software program(s) and the Seller Portal in sync - meaning less time and effort for you, as no human intervention is needed.

Which Seller Portal data flows can currently be automated in the Seller API?

If you integrate your software program(s) with the Seller Portal via the Seller API:

You will currently be able to automate updates of your:
- Selling price
- Recommended Retail Price (RRP)
- Leadtime days
- Leadtime SoH
- Product Offer status (active/inactive/archived)
...for both your existing Product Offers and Offers you would like to create using products that already exist in Takealot’s catalogue.
You will be able to retrieve Sale information, including:
- Order Date, Sale Status, Order ID, Order Item ID
- Product Title, Takealot Product Display Page URL (for Mobile site)
- SKU, TSIN, Offer ID, Quantity, Selling Price

Versioning

The Takealot Seller API is versioned on a Major.Minor.Patch basis, e.g. 1.2.0. You are only required to provide the Major version when calling an endpoint on the Seller API, prefixed with a v, e.g. v1.

Authentication

To authenticate against the API, include your API key in the 'Authorization' header, prefixed with 'Key', in every request.

Authorization: Key <yourapikey>

Note: API keys are only presented upon initial generation. Please store them in a safe location as they cannot be retrieved later and will need to be regenerated if lost.

Rate Limits

Rate limits are flexible and vary by endpoint. Details are included in response headers:

Header	Definition
x-RateLimit-Limit	The maximum number of requests you can make in the limit window
x-RateLimit-Remaining	The number of requests you have remaining in this window
x-RateLimit-Reset	The time at which the window and your remaining requests will reset

If you exceed the rate limits, the API will return an HTTP 429 Too Many Requests response.

API Integration Best Practices

Initial Migration Strategy

When an API endpoint has the capability of adding a date filter, restrict the date range to 180 days at a time and page through it. This should be done as a once off activity. Future data should be processed via webhooks.

Getting Updates (Webhooks vs Polling)

Webhooks: Provide an asynchronous method to find updates. Use the webhook payload as the most up-to-date information.
Avoid Polling: Interval based pulling of data is not recommended.
Don't query slow changing data: Offer information rarely changes. Use the Offer Updated webhook. Similarly, use the Sale Status Changed webhook for sales.

Pushing Updates

When updating offer information, it's preferred to do updates in batches (limit 10,000 updates). Use the Batch Completed webhook to keep track.

For singular offer updates, prefer using the Offer ID as the identifier.

Offers API

Versioning & Terminology Changes

gtin has now become barcode
price has now become selling_price
status has now become status_action (Inputs: Re-enable, Disable).
Leadtime Stock has changed from a single number to a list of objects containing warehouse ID and quantity.

Terms & Definitions

Term	Reference	Definition
Barcode	barcode	Global Trade Identification number (EAN-13/ISBN-13).
Leadtime	leadtime_days	Working days required to deliver a Leadtime order to our DC.
Leadtime Stock	leadtime_stock	List of stock quantities available at your warehouses.
Offer ID	offer_id	Your Product Offer's unique identifier.
Product Label	product_label_number	Takealot's internal Marketplace barcode (99-Barcode).
Selling Price	selling_price	Price at which you sell to customers.
SKU	sku	Your own unique identifier.
Stock at Takealot	stock_at_takealot	Stock available in Takealot DCs.
TSIN	tsin	Takealot's unique identifier for a variant/product.

Rules & Requirements

An offer that is Disabled by Takealot cannot have its details updated.
An offer always requires a price before it can be made buyable.
Setting leadtime days to 0 will automatically set leadtime stock to 0.
An offer's RRP must be higher than the selling price.
An offer will only be buyable if:
- Selling Price set AND (Leadtime Stock > 0 + Leadtime > 0) AND Status = Buyable
- OR Selling Price set AND Stock at Takealot > 0 AND Status = Buyable
If using SKUs with special characters (?, #, /, :), use the identifier endpoint and URL encode the SKU.

A Note on Batches

Size Limit: Any upload that has more than 10,000 offers will be rejected.

Order of Identifier Preference

If multiple identifiers are provided, precedence is:

Offer ID (Primary)
Barcode (Secondary if with Offer ID, Primary if alone/with SKU)
SKU (Update parameter if with others, Primary if alone)

Validation Errors

Code	Message
E1	Offer could not be created - not eligible for marketplace.
E2	Failed to create offer. A matching barcode could not be found.
E3	Failed to create offer. No barcode provided.
E4	Failed to create offer. Barcode already exists for this account.
E5	TSIN and TSIN on record for barcode do not match.
E6	Failed to create SKU. SKU already exists.
E7	TSIN provided does not match an existing offer.
E8	SKU provided does not match an existing offer.
E9	Offer x does not belong to merchant x.
E10	Failed to update SKU. SKU already exists.
E11	Cannot disable offer when "Disabled by Takealot".
E12	Cannot re-enable offer when "Disabled by Takealot".
E13	Cannot update SKU when "Disabled by Takealot".
E14	Cannot update leadtime when "Disabled by Takealot".
E15	My SoH must be a whole number >= 0.
E16	Leadtime disabled for this offer.
E17	Cannot update My SoH when "Disabled by Takealot".
E18	Leadtime days set to "None". Update leadtime days first.
E19	Selling price must be whole number >= 0.
E20	Selling price must be <= RRP.
E21	Cannot update selling price when "Disabled by Takealot".
E22	RRP must be whole number >= 0.
E23	RRP must be >= selling price.
E24	Cannot update RRP when "Disabled by Takealot".
E25	Not eligible for minimum leadtime days.
E26	Not eligible for maximum leadtime days.
E27	SKU exceeds 255 characters.
E28	Update to leadtime not permitted. Leadtime disabled.
E29	Merchant is not active on platform.
E30	Can't update stock to less than zero.
E31	Offer ID provided does not match an existing offer.
E32	TSIN provided does not match the given offer's TSIN.
E33	Barcode provided does not match the given offer's barcode.

Sales API

Terms & Definitions

Term	Reference	Definition
Order ID	order_id	Unique numeric identifier for a customer order.
Order Item ID	order_item_id	Identifier of an individual item within an Order.
Sale Status	sale_status	Current status within fulfillment process.
Fulfilment DC	dc	DC from where the order is fulfilled (CPT; JHB; DBN).
Customer DC	customer_dc	Nearest DC to customer's address (CPT; JHB; DBN).
PO Number	po_number	Identifier for confirmed Shipment ("PO").

Important Note (Sales)

We have introduced a 180 days date range limit on the Sales API.

If you use a date filter > 180 days, you will receive an error and no data.
If you omit start/end dates, we default to a 180 day period.
If you do not use a date filter, we return the last 30 days.

Webhooks

Webhooks update your system in real time based on events in the Seller Portal. Instead of polling APIs, subscribe to events to receive POST requests when they occur.

Configuration & Headers

Payload Headers:

X-Takealot-Event: The event type
X-Takealot-Delivery: UUID for this delivery
X-Takealot-Signature: HMAC hex digest of response body (for verification)

Retry Policy

Failed webhooks will be re-attempted 3 times over a period of 6 minutes. Respond with a 200 OK within 5 seconds to acknowledge receipt.

WEBHOOK

New Leadtime Order

Notification for each new leadtime order item. Use this to decrement your Offer's leadtime_stock value locally.

{
    "order_id": 12345,
    "order_item_id": 67890,
    "offer": {
        "offer_id": 111,
        "sku": "SKU-123",
        "barcode": "600123456789",
        "leadtime_stock": [
            {
                "merchant_warehouse": {
                    "warehouse_id": 1,
                    "name": "JHB Warehouse"
                },
                "quantity_available": 50
            }
        ]
    },
    "warehouse": "JHB",
    "total_selling_price": 250,
    "quantity": 1,
    "event_date": "2023-10-27T10:00:00",
    "facility": {
        "code": "JHB2",
        "address": "123 Street Name"
    }
}

WEBHOOK

New Drop Ship Order

Notification for each new drop ship order.

{
    "order_id": 54321,
    "ready_for_collect_due_date": "2023-11-01",
    "acceptance_due_date": "2023-10-29",
    "merchant_warehouse": {
          "warehouse_id": 5,
          "name": "CPT Warehouse"
    },
    "offers": [
      {
        "offer": {
            "offer_id": 999,
            "sku": "DS-ITEM-1",
            "barcode": "600999999",
            "leadtime_stock": [
              {
                    "merchant_warehouse": {
                          "warehouse_id": 5,
                          "name": "CPT Warehouse"
                    },
                    "quantity_available": 10
              }
            ]
        },
        "quantity_required": 2
      }
    ],
    "event_date": "2023-10-27T12:00:00"
}

WEBHOOK

Sale Status Changed

Notification of each new sale or sale status update (e.g. Shipped, Returned).

{
    "sale": {
        "order_item_id": 777,
        "order_id": 888,
        "order_date": "2023-10-20",
        "sale_status": "Shipped to Customer",
        "offer_id": 123,
        "tsin": 456,
        "sku": "ABC-123",
        "customer": "Doe, John",
        "product_title": "Blue Widget",
        "takealot_url_mobi": "http://...",
        "selling_price": 100,
        "quantity": 1,
        "warehouse": "CPT",
        "customer_warehouse": "CPT",
        "promotion": "Black Friday",
        "shipment_id": 900,
        "shipment_state_id": 2,
        "po_number": 555,
        "shipment_name": "PO-555",
        "takealot_url": "http://..."
      },
      "event_timestamp_utc": "2023-10-22T14:30:00"
}

WEBHOOK

Batch Completed

Notification when a bulk upload batch has been completed. Status can be SUCCESS or FAILURE.

{
    "seller_id": 1001,
    "batch_id": 5005,
    "status": "SUCCESS"   
}

WEBHOOK

Offer Updated

Notification when an offer has been updated and which fields were affected.

{
    "seller_id": 1001,
    "offer_id": 2002,
    "values_changed": {
        "selling_price": 150
    },
    "batch_id": 5005    
}

WEBHOOK

Offer Created

Notification when an offer has been created.

{
    "seller_id": 1001,
    "offer_id": 3003,
    "merchant_sku": "NEW-ITEM-01",
    "tsin_id": 4004,
    "gtin": "600111222333",
    "minimum_leadtime_days": 2,
    "maximum_leadtime_days": 5,
    "selling_price": 200,
    "rrp": 250,
    "merchant_warehouse_stock": [
        { "warehouse_id": 1, "quantity": 100 }
    ],
    "batch_id": 5005    
}

Takealot Seller Guide

Takealot Seller API

What is an API?

Which Seller Portal data flows can currently be automated in the Seller API?

Versioning

Authentication

Rate Limits

API Integration Best Practices

Initial Migration Strategy

Getting Updates (Webhooks vs Polling)

Pushing Updates

Offers API

Versioning & Terminology Changes

Terms & Definitions

Rules & Requirements

A Note on Batches

Order of Identifier Preference

Validation Errors

Sales API

Terms & Definitions

Important Note (Sales)

Webhooks

Configuration & Headers

Retry Policy

New Leadtime Order

New Drop Ship Order

Sale Status Changed

Batch Completed

Offer Updated

Offer Created