2khat Catalog Sync

2khat connects your WooCommerce store to the 2khat platform by exposing a secure, paginated REST API for product catalog synchronization.

After registering your store with the 2khat team, install and activate this plugin to allow 2khat to fetch your published products and variations.

Security

public_key.pem is the 2khat RSA public key used to verify API request signatures. It is not a private credential and must remain in the plugin directory.<h3>Authentication</h3>

All 2khat API requests require RSA domain signature verification.

Signing (2khat server side):

1. Normalize the store domain: use the host from site_url(), without a www. prefix.
2. Sign the domain string with the 2khat private key using SHA256.
3. Base64-encode the binary signature.

4. Send it in the request header:

   Authorization: Twokcs

Legacy clients may also use Authorization: Basic <base64-signature> during migration.

Example (OpenSSL CLI):

`

echo -n “example.com” | openssl dgst -sha256 -sign 2khat_private.pem | openssl base64 -A
<h3>REST API</h3>
**GET**/wp-json/twokcs/v1/version`

Returns the plugin version.

GET /wp-json/twokcs/v1/products?page=1&per_page=100

Returns paginated published products with nested variations.

GET /wp-json/twokcs/v1/categories?page=1&per_page=100

Returns paginated product categories.

GET /wp-json/twokcs/v1/attributes?page=1&per_page=100

Returns paginated product attributes.

GET /wp-json/twokcs/v1/attribute-terms?page=1&per_page=100

Returns paginated attribute terms across all attributes. Optionally filter by attribute:

GET /wp-json/twokcs/v1/attribute-terms?attribute_id=1&page=1&per_page=100

GET /wp-json/twokcs/v1/variants?product_ids=10,20

Returns compact published variants grouped by parent product ID. Each item includes parent product fields (product_id, type, manage_stock, price, regular_price, sale_price, stock_quantity, stock_status) and a variants array with: id, on_sale, status, price, regular_price, sale_price, stock_quantity, stock_status. Simple products return an empty variants array and their own price/stock on the parent object.

GET /wp-json/twokcs/v1/variants?ids=305,306,307

Returns compact published variants for the given variation IDs in request order. Response shape: { count, results: [...] } with the same variant fields as above.

GET /wp-json/twokcs/v1/variant?id=305

Returns a single compact published variant object with the same fields as above. Returns 404 when the variation is missing or not published.

POST /wp-json/twokcs/v1/orders

Creates a WooCommerce order for the 2khat platform.

Request body (JSON):

• external_order_id (required) — platform order id, stored as _twokcs_external_order_id
• line_items (required) — array of { product_id, variation_id?, quantity, external_item_id? }; external_item_id is the platform line item id, stored as _twokcs_external_item_id and usable in /order/update
• billing / shipping — address objects
• status — WooCommerce status without wc- prefix (default: processing)
• customer_note — optional note
• meta_data — optional array of { key, value } (public keys and _twokcs_* only)

Returns 201 with a compact order object. Duplicate external_order_id returns 409 with existing_order_id.

GET /wp-json/twokcs/v1/order

Lists orders as { count, max_pages, results }. All filters are optional and combinable: id (single or comma-separated, e.g. id=12,13), external_order_id, status, plus page / per_page. Bare GET /order returns a paginated list. No matches return an empty results array (200). If both id and external_order_id are provided and refer to different orders, the request returns 400.

Examples:

• /wp-json/twokcs/v1/order
• /wp-json/twokcs/v1/order?status=processing
• /wp-json/twokcs/v1/order?id=123
• /wp-json/twokcs/v1/order?id=123,124,125
• /wp-json/twokcs/v1/order?external_order_id=2khat-12345
• /wp-json/twokcs/v1/order?id=123&status=processing

Each result includes: id, status, external_order_id, tracking_code, tracking_provider, shipping_method, date_created, date_modified, total, currency, line_items (each with id, external_item_id, product_id, variation_id, name, quantity, total).

POST /wp-json/twokcs/v1/order/update

Changes line items of a 2khat order in pending, processing, or on-hold status (including paid orders).

Request body (JSON):

• id and/or external_order_id (one required) — the order to update
• line_items (required) — array where each entry is either:
  • { id, quantity } — change an existing line item (id from the order’s line_items[].id); quantity: 0 removes it
  • { external_item_id, product_id, variation_id?, quantity } — change the line item created with that external_item_id. For orders created before 1.1.0, falls back to the single untagged line item with the same product_id / variation_id. An unknown external_item_id with quantity > 0 adds a new item; with quantity 0 it is ignored
  • { product_id, variation_id?, quantity } — add a new item
• reason — optional text added to the order note

Items not listed stay unchanged. All entries are validated before any change is applied. Existing items keep their original unit price; new items use the current product price. Stock is adjusted when the order has already reduced stock. Totals are recalculated and an order note records the change; no refund is issued.

Returns 200 with the compact order object plus previous_total. Removing every item returns 400 (twokcs_order_empty) — use cancel instead. Unknown order or line item returns 404; non-editable status returns 409.

POST /wp-json/twokcs/v1/order/cancel

Cancels a whole 2khat order in pending, processing, or on-hold status. WooCommerce restores reduced stock. No refund is issued.

Request body (JSON): id and/or external_order_id (one required), optional reason.

Returns 200 with the compact order object (also when the order is already cancelled). Unknown order returns 404; other statuses return 409.

Only orders created through POST /orders (carrying _twokcs_external_order_id) can be updated or cancelled.

Query parameters (all catalog endpoints):

• page — page number (default: 1, minimum: 1)
• per_page — items per page (default: 100, maximum: 200)
• attribute_id — (attribute-terms only) filter terms to a single attribute
• product_ids — (variants only) comma-separated parent product IDs; returns variants grouped by product
• ids — (variants only) comma-separated variation IDs; returns a flat list in request order
• id — (variant / order) single variation ID, or WooCommerce order ID(s), comma-separated for orders
• external_order_id — (order only) filter by 2khat external order id meta
• status — (order only) optional WooCommerce status filter
• debug — include SQL query stats only when WP_DEBUG and TWOKCS_DEBUG are enabled, or when the twokcs_allow_debug filter returns true. Full query details require SAVEQUERIES enabled in wp-config.php.