Custom Store API Reference

Help Center

Custom Store API

Send orders, abandoned carts and products to Replyk from any system, with one URL and one secret.

Getting Started

For custom platforms. You receive a webhook endpoint and secret to send orders from any system.

Create a Manual Connection

Go to Store Connections, click + Add Connection, select Manual/Custom, name it, and save.

Save the webhook secret immediately. It won't be shown again.

Authenticate Your Requests

Include your webhook secret in the x-webhook-secret header.

http

POST /api/store-webhook/manual/{connectionId}
Content-Type: application/json
x-webhook-secret: YOUR_WEBHOOK_SECRET

Pick an Endpoint

Every endpoint starts with the webhook URL shown on your connection.

Create a productPOST /api/store-webhook/manual/{connectionId}/products

Create an orderPOST /api/store-webhook/manual/{connectionId}

Report an abandoned cartPOST /api/store-webhook/manual/{connectionId}

Create a product

Add a product to your Replyk catalog from your own system. The Agent can sell it as soon as the request succeeds.

http

POST /api/store-webhook/manual/{connectionId}/products
Content-Type: application/json
x-webhook-secret: YOUR_WEBHOOK_SECRET

{
 "name": "Argan Oil 100ml",
 "sku": "ARG-100",
 "price": 150.00
}

Fields

nameRequiredProduct name, up to 100 characters.

skuRequiredYour unique product code. Order items are matched to products by SKU.

priceRequiredSelling price, in your business currency.

descriptionUp to 2000 characters. The Agent uses it to answer customer questions.

categoryFree text, used to group products.

stockUnits available. Defaults to 0.

is_activeSend false to create the product without the Agent selling it yet. Defaults to true.

image_urlPublic URL of the main photo.

additional_imagesUp to 20 more public image URLs.

variant_optionsThe options a customer chooses from, such as Size or Color, with their values.

variantsOne entry per combination. Each needs its own sku, price and options.

A product with variants

json

{
 "name": "Classic T-Shirt",
 "sku": "TSHIRT",
 "price": 199.00,
 "description": "Heavy cotton, regular fit.",
 "category": "Clothing",
 "stock": 40,
 "is_active": true,
 "image_url": "https://yourstore.com/images/tshirt.jpg",
 "additional_images": [
 "https://yourstore.com/images/tshirt-back.jpg"
 ],
 "variant_options": [
 { "name": "Size", "values": ["M", "L"] }
 ],
 "variants": [
 { "sku": "TSHIRT-M", "price": 199.00, "stock": 25, "options": { "Size": "M" } },
 { "sku": "TSHIRT-L", "price": 199.00, "stock": 15, "options": { "Size": "L" } }
 ]
}

Test with cURL

bash

curl -X POST \
 https://replyk.io/api/store-webhook/manual/{connectionId}/products \
 -H "Content-Type: application/json" \
 -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
 -d '{
 "name": "Argan Oil 100ml",
 "sku": "ARG-100",
 "price": 150,
 "stock": 40,
 "image_url": "https://yourstore.com/images/argan.jpg"
 }'

Success (201):

json

{
 "success": true,
 "product": {
 "id": "4b1f6c1e-8a53-4f0e-9a43-2f3f3d1c9b7a",
 "sku": "ARG-100",
 "name": "Argan Oil 100ml",
 "price": "150",
 "stock": 40,
 "is_active": true,
 "created_at": "2026-10-03T10:15:00.000Z"
 }
}

Error (400):

json

{
 "statusCode": 400,
 "message": "Product with SKU \"ARG-100\" already exists in this business"
}

Other codes: 400 (invalid field, or the SKU already exists), 403 (invalid secret, or your plan's product limit is reached), 404 (connection not found or inactive), 429 (more than 60 requests per minute).

This endpoint only creates products. To change one later, edit it in the Products tab.

Create an order

Required fields: external_order_id, customer_name, customer_phone, total_amount, items (array with sku, quantity, price).

json

{
 "external_order_id": "ORD-12345",
 "external_order_number": "INV-2026-001",
 "customer_name": "Sara Amrani",
 "customer_phone": "+14155550123",
 "customer_email": "sara@example.com",
 "customer_address": "123 Main St",
 "customer_city": "Springfield",
 "customer_country": "US",
 "total_amount": 350.00,
 "subtotal": 300.00,
 "shipping_cost": 50.00,
 "discount": 0,
 "currency_code": "USD",
 "payment_method": "COD",
 "notes": "Please deliver in the morning",
 "items": [
 {
 "sku": "ARG-100",
 "quantity": 2,
 "price": 150.00
 }
 ]
}

Test with cURL

bash

curl -X POST \
 https://replyk.io/api/store-webhook/manual/{connectionId} \
 -H "Content-Type: application/json" \
 -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
 -d '{
 "external_order_id": "ORD-12345",
 "customer_name": "Sara Amrani",
 "customer_phone": "+14155550123",
 "total_amount": 300,
 "currency_code": "USD",
 "items": [
 { "sku": "ARG-100", "quantity": 2, "price": 150 }
 ]
 }'

Success (200):

json

{
 "success": true,
 "duplicate": false,
 "order_id": "9d2c7f0a-5b1e-4c3d-8f6a-1e2b3c4d5e6f",
 "order_number": "ORD-26-276-01-A1",
 "status": "DRAFT"
}

Other codes: 403 (invalid secret), 404 (connection not found or inactive). Sending the same external_order_id again is safe: it returns success without creating a second order.

Report an abandoned cart

Send a checkout to the order URL with one extra header, and the Agent can message the shopper if they never finish.

http

POST /api/store-webhook/manual/{connectionId}
Content-Type: application/json
x-webhook-secret: YOUR_WEBHOOK_SECRET
x-webhook-event: abandoned_cart

{
 "external_checkout_id": "CART-98765",
 "customer_name": "Sara Amrani",
 "customer_phone": "+14155550123",
 "customer_city": "Springfield",
 "total_amount": 350.00,
 "currency_code": "USD",
 "recovery_url": "https://yourstore.com/cart/recover/98765",
 "items": [
 { "sku": "ARG-100", "quantity": 2, "price": 150.00 }
 ]
}

Send the same cart again on every update, keeping external_checkout_id the same, and the wait period restarts each time. The fields match an order payload; recovery_url is the link back into the customer's cart.

Still need help?

Our team replies within one business day. Tell us what you're stuck on and we'll guide you through it.

Contact support

Browse all help topics