Overview
The Rep AI External SDK provides a comprehensive REST API for non-Shopify e-commerce platforms to integrate with Rep AI's AI-powered shopping assistant. This SDK enables merchants to sync their catalog data, handle order events, manage customer data for GDPR compliance, and leverage Rep AI's conversational commerce capabilities.
Base URL
Production: <https://server.hellorep.ai>
Authentication
All API requests require authentication using an API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
How to get your API key:
Log into your Rep AI dashboard
Navigate to Settings → API Keys
Generate or copy your API key
Common Request Headers
{
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
Common Response Format
Success Response
{
"status": "success",
"message": "Operation completed successfully",
"data": {
// Response data
}
}
Error Response
{
"status": "error",
"message": "Error description",
"code": "ERROR_CODE"
}
1. Product Management APIs
1.1 Sync Product
Creates or updates a product in Rep AI's catalog.
Endpoint: POST /external/v1/products
Request Body:
{
"account_key": "your-account-key",
"id": "prod_123",
"title": "Wireless Bluetooth Headphones",
"description": "Premium noise-canceling wireless headphones with 30-hour battery life",
"vendor": "AudioTech",
"product_type": "Electronics",
"handle": "wireless-bluetooth-headphones",
"shoppable": true,
"archived": false,
"image_url": "<https://example.com/images/headphones-main.jpg>",
"online_store_url": "<https://yourstore.com/products/wireless-bluetooth-headphones>",
"internal_entity_url": "<https://admin.yourstore.com/products/prod_123>",
"variants": [
{
"id": "var_123_black",
"title": "Black",
"price": {
"original": 249.99,
"current": 199.99
},
"sku": "WBH-001-BLK",
"quantity": 50,
"image_url": "<https://example.com/images/headphones-black.jpg>"
},
{
"id": "var_123_white",
"title": "White",
"price": {
"original": 249.99,
"current": 199.99
},
"sku": "WBH-001-WHT",
"quantity": 30,
"image_url": "<https://example.com/images/headphones-white.jpg>"
}
],
"option_names": ["Color"],
"tags": ["wireless", "bluetooth", "headphones", "premium"],
"in_group_ids": ["collection_electronics", "collection_featured"],
"meta_fields": {
"battery_life": "30 hours",
"connectivity": "Bluetooth 5.0",
"noise_canceling": "Active"
}
}
Response:
{ "status": "success", "product_id": "prod_123" }
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
Yes |
Unique product identifier in your system |
|
string |
Yes |
Product name (max 500 characters) |
|
string |
No |
Product description (max 50KB) |
|
string |
No |
Product manufacturer/brand |
|
string |
No |
Product category |
|
string |
No |
URL-friendly product identifier |
|
boolean |
No |
Whether product is available for purchase (default: true) |
|
boolean |
No |
Whether product is archived (default: false) |
|
string |
No |
Main product image URL |
|
string |
No |
Link to product page on your store |
|
string |
No |
Link to product in your admin system |
|
array |
Yes |
Product variants (max 1000) |
|
array |
No |
Product option names (color, size, etc.) |
|
array |
No |
Product tags (max 50, each max 100 chars) |
|
array |
No |
Collection IDs this product belongs to |
|
object |
No |
Custom product attributes |
Variant Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Unique variant identifier |
|
string |
No |
Variant title/name |
|
object |
Yes |
Pricing information |
|
string |
No |
Stock keeping unit |
|
integer |
No |
Available inventory quantity |
|
string |
No |
Variant-specific image URL |
Price Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
number |
No |
Original price (before discount) |
|
number |
Yes |
Current selling price |
1.2 Delete Product
Archives a product from Rep AI's catalog.
Endpoint: DELETE /external/v1/products/{product_id}?account_key={account_key}
Parameters:
product_id(path): The product ID to deleteaccount_key(query): Your account key
Response:
{ "status": "success", "message": "Product archived successfully" }
2. Product Group Management APIs
2.1 Sync Product Group
Creates or updates a product group (collection) in Rep AI's catalog.
Endpoint: POST /external/v1/product-groups
Request Body:
{
"account_key": "your-account-key",
"id": "collection_electronics",
"title": "Electronics",
"description": "All electronic products including headphones, speakers, and accessories",
"handle": "electronics",
"active": true,
"collection_url": "<https://yourstore.com/collections/electronics>",
"product_ids": ["prod_123", "prod_456", "prod_789"]
}
Response:
{ "status": "success", "group_id": "collection_electronics" }
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
Yes |
Unique collection identifier |
|
string |
Yes |
Collection name (max 255 characters) |
|
string |
No |
Collection description (max 10KB) |
|
string |
No |
URL-friendly collection identifier |
|
boolean |
No |
Whether collection is active/published (default: true) |
|
string |
No |
Link to collection page |
|
array |
No |
Products in this collection (max 10,000) |
2.2 Delete Product Group
Archives a product group from Rep AI's catalog.
Endpoint: DELETE /external/v1/product-groups/{group_id}?account_key={account_key}
Parameters:
group_id(path): The product group ID to deleteaccount_key(query): Your account key
Response:
{ "status": "success", "message": "Product group archived successfully" }
3. Meta-Field Management APIs
3.1 Register Meta-Field
Registers a custom meta-field that can be used with products or collections.
Endpoint: POST /external/v1/meta-fields
Request Body:
{
"account_key": "your-account-key",
"id": "battery_life",
"key": "battery_life",
"name": "Battery Life",
"description": "Device battery life in hours",
"value": "30 hours",
"for_catalog_entity": "PRODUCT",
"value_type": "STRING",
"enabled": true
}
Response:
{
"status": "success",
"meta_field_id": "battery_life",
"message": "Meta-field registered successfully"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
No |
Meta-field identifier (auto-generated if not provided) |
|
string |
Yes |
Meta-field key (alphanumeric, dots, underscores, hyphens) |
|
string |
No |
Display name for the meta-field |
|
string |
No |
Meta-field description |
|
object |
No |
Default value for the meta-field |
|
string |
Yes |
Entity type: "PRODUCT" or "PRODUCT_GROUP" |
|
string |
Yes |
Data type: "STRING", "INTEGER", "DECIMAL", "BOOLEAN" |
|
boolean |
No |
Whether meta-field is active (default: false) |
4. Discount Management APIs
4.1 Sync Discount
Creates or updates a discount in Rep AI's system.
Endpoint: POST /external/v1/discounts
Request Body:
{
"account_key": "your-account-key",
"id": "summer_sale_2024",
"name": "Summer Sale 2024",
"code": "SUMMER20",
"description": "Summer promotional discount",
"discount_type": "PERCENTAGE",
"value": 20.0,
"minimum_order_amount": 100.0,
"usage_limit": 1000,
"usage_count": 0,
"starts_at": "2024-06-01T00:00:00Z",
"ends_at": "2024-08-31T23:59:59Z",
"active": true,
"discount_application_type": "AUTOMATIC",
"once_per_customer": true,
"applicable_product_ids": ["prod_123", "prod_456"],
"excluded_product_ids": ["prod_999"],
"prerequisite_product_ids": ["prod_001"],
"prerequisite_variant_ids": ["var_001"],
"prerequisite_group_ids": ["collection_electronics"]
}
Response:
{
"status": "success",
"discount_id": "summer_sale_2024",
"message": "Discount synced successfully"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
Yes |
Unique discount identifier |
|
string |
Yes |
Discount display name |
|
string |
No |
Discount code customers enter |
|
string |
No |
Discount description |
|
string |
Yes |
"PERCENTAGE", "FIXED_AMOUNT", "FREE_SHIPPING" |
|
number |
Yes |
Discount value (percentage or amount) |
|
number |
No |
Minimum order value to apply discount |
|
integer |
No |
Maximum number of uses |
|
integer |
No |
Current number of uses |
|
string |
No |
Start date (ISO 8601 format) |
|
string |
No |
End date (ISO 8601 format) |
|
boolean |
No |
Whether discount is active |
|
string |
No |
How discount is applied: "AUTOMATIC", "MANUAL" |
|
boolean |
No |
Whether discount can only be used once per customer |
|
array |
No |
Products this discount applies to |
|
array |
No |
Products excluded from this discount |
|
array |
No |
Products required in cart for discount |
|
array |
No |
Variants required in cart for discount |
|
array |
No |
Collections required in cart for discount |
4.2 Delete Discount
Archives a discount from Rep AI's system.
Endpoint: DELETE /external/v1/discounts/{discount_id}?account_key={account_key}
Parameters:
discount_id(path): The discount ID to deleteaccount_key(query): Your account key
Response:
{ "status": "success", "message": "Discount archived successfully" }
5. Order Event APIs
5.1 Order Completed Event
Notifies Rep AI when a customer completes an order.
Endpoint: POST /external/v1/events/order-completed
Request Body:
{
"account_key": "your-account-key",
"order_id": "order_12345",
"order_number": "12345",
"order_name": "#12345",
"checkout_id": "checkout_abc123",
"cart_token": "cart_xyz789",
"customer_id": "customer_456",
"customer_email": "john.doe@example.com",
"customer_first_name": "John",
"customer_last_name": "Doe",
"customer_phone": "+1-555-123-4567",
"customer_tags": "vip,returning",
"total_price": 249.99,
"subtotal_price": 199.99,
"tax_amount": 20.00,
"shipping_amount": 15.99,
"discount_amount": 15.00,
"currency_code": "USD",
"creation_date": "2024-01-15T10:30:00Z",
"financial_status": "paid",
"order_status_url": "<https://yourstore.com/orders/12345>",
"rep_session_id": "session_abc123",
"browser_ip": "192.168.1.100",
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"company": "Tech Corp",
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "New York",
"province": "NY",
"province_code": "NY",
"country": "United States",
"country_code": "US",
"zip": "10001",
"phone": "+1-555-123-4567"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"company": "Tech Corp",
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "New York",
"province": "NY",
"province_code": "NY",
"country": "United States",
"country_code": "US",
"zip": "10001",
"phone": "+1-555-123-4567"
},
"line_items": [
{
"product_id": "prod_123",
"variant_id": "var_123_black",
"name": "Wireless Bluetooth Headphones - Black",
"quantity": 1,
"price": 199.99,
"total_price": 199.99
}
],
"applied_discounts": [
{
"discount_id": "summer_sale_2024",
"code": "SUMMER20",
"amount": 15.00
}
],
"order_attributes": [
{
"name": "gift_message",
"value": "Happy Birthday!"
}
]
}
Response:
{
"status": "success",
"order_id": "order_12345",
"message": "Order completion processing started"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
Yes |
Unique order identifier in your system |
|
string |
No |
Human-readable order number |
|
string |
No |
Display name for the order (e.g., "#12345") |
|
string |
No |
Checkout session identifier |
|
string |
No |
Shopping cart token |
|
string |
No |
Unique customer identifier |
|
string |
No |
Customer email address |
|
string |
No |
Customer first name |
|
string |
No |
Customer last name |
|
string |
No |
Customer phone number |
|
string |
No |
Comma-separated customer tags |
|
number |
Yes |
Total order amount including taxes and shipping |
|
number |
No |
Subtotal before taxes and shipping |
|
number |
No |
Total tax amount |
|
number |
No |
Shipping cost |
|
number |
No |
Total discount applied |
|
string |
Yes |
ISO 4217 currency code (e.g., "USD", "EUR") |
|
string |
No |
Order creation date (ISO 8601 format) |
|
string |
No |
Payment status: "pending", "paid", "refunded", etc. |
|
string |
No |
URL to view order status |
|
string |
No |
Rep AI session ID (for attribution) |
|
string |
No |
Customer's IP address |
|
object |
No |
Customer shipping address |
|
object |
No |
Customer billing address |
|
array |
Yes |
Products in the order |
|
array |
No |
Discounts applied to the order |
|
array |
No |
Custom order attributes |
Address Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
No |
First name |
|
string |
No |
Last name |
|
string |
No |
Company name |
|
string |
No |
Primary address line |
|
string |
No |
Secondary address line (apt, suite, etc.) |
|
string |
No |
City name |
|
string |
No |
State/province name |
|
string |
No |
State/province code |
|
string |
No |
Country name |
|
string |
No |
ISO country code |
|
string |
No |
Postal/ZIP code |
|
string |
No |
Phone number |
Line Item Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Product identifier |
|
string |
No |
Product variant identifier |
|
string |
Yes |
Product name |
|
integer |
Yes |
Quantity ordered |
|
number |
Yes |
Unit price |
|
number |
Yes |
Total price (quantity × unit price) |
Applied Discount Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
No |
Discount identifier |
|
string |
No |
Discount code used |
|
number |
Yes |
Discount amount |
Order Attribute Object Fields:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Attribute name |
|
string |
Yes |
Attribute value |
5.2 Order Status Update Event
Updates the status of an existing order (fulfillment, shipping, delivery status changes).
Endpoint: POST /external/v1/events/order-status-update
Request Body:
{
"account_key": "your-account-key",
"order_id": "order_12345",
"status": "shipped",
"tracking_url": "<https://fedex.com/track/1234567890>",
"estimated_delivery": "2024-01-20T14:00:00Z",
"consumer_id": "customer_456",
"consumer_name": "John Doe",
"consumer_first_name": "John",
"consumer_last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1-555-123-4567",
"line_items": [
{
"product_id": "prod_123",
"variant_id": "var_123_black",
"name": "Wireless Bluetooth Headphones - Black",
"quantity": 1,
"price": 199.99,
"total_price": 199.99
}
],
"shipping_address": {
"first_name": "John",
"last_name": "Doe",
"address1": "123 Main St",
"address2": "Apt 4B",
"city": "New York",
"province": "NY",
"country": "United States",
"zip": "10001",
"phone": "+1-555-123-4567"
}
}
Response:
{
"status": "success",
"order_id": "order_12345",
"message": "Order status update processing started"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
Yes |
Unique order identifier in your system |
|
string |
No |
Order status (see supported statuses below) |
|
string |
No |
Shipment tracking URL |
|
string |
No |
Estimated delivery date (ISO 8601 format) |
|
string |
No |
Customer identifier |
|
string |
No |
Full customer name |
|
string |
No |
Customer first name |
|
string |
No |
Customer last name |
|
string |
No |
Customer email address |
|
string |
No |
Customer phone number |
|
array |
No |
Updated line items (uses same structure as order completed) |
|
object |
No |
Updated shipping address (uses same structure as order completed) |
Supported Order Statuses:
pending- Order is pendingauthorized- Payment authorizedpartially_paid- Partial payment receivedpaid- Payment completedpartially_refunded- Partial refund issuedrefunded- Full refund issuedvoided- Order voidedfulfilled- Order fulfilledshipped- Order shippeddelivered- Order delivered
6. GDPR Compliance APIs
6.1 Customer Data Request
Handles customer data requests for GDPR compliance.
Endpoint: POST /external/v1/privacy/customer-data-request
Request Body:
{
"account_key": "your-account-key",
"customer_email": "john.doe@example.com",
"customer_id": "customer_456",
"request_id": "gdpr_req_12345",
"request_details": "Customer requested personal data export"
}
Response:
{
"status": "received",
"message": "Request acknowledged"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
No |
Customer email address |
|
string |
No |
Customer identifier |
|
string |
No |
Unique request identifier |
|
string |
No |
Additional details about the request |
6.2 Customer Data Deletion
Handles customer data deletion requests for GDPR compliance.
Endpoint: POST /external/v1/privacy/customer-data-deletion
Request Body:
{
"account_key": "your-account-key",
"customer_email": "john.doe@example.com",
"customer_id": "customer_456",
"request_id": "gdpr_del_12345"
}
Response:
{
"status": "received",
"message": "Deletion request acknowledged"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
No |
Customer email address |
|
string |
No |
Customer identifier |
|
string |
No |
Unique request identifier |
6.3 Store Data Deletion
Handles complete store data deletion for GDPR compliance.
Endpoint: POST /external/v1/privacy/store-data-deletion
Request Body:
{
"account_key": "your-account-key",
"shop_domain": "yourstore.com",
"request_id": "store_del_12345"
}
Response:
{
"status": "received",
"message": "Store deletion request acknowledged"
}
Field Descriptions:
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
Your Rep AI account identifier |
|
string |
No |
Store domain name |
|
string |
No |
Unique request identifier |
Error Codes and Troubleshooting
Common Error Codes
Code |
Description |
Solution |
|---|---|---|
|
Bad Request |
Check request format and required fields |
|
Unauthorized |
Verify API key is correct and included in header |
|
Forbidden |
Check account permissions |
|
Not Found |
Verify endpoint URL and resource existence |
|
Validation Error |
Review field validation requirements |
|
Rate Limit Exceeded |
Reduce request frequency |
|
Internal Server Error |
Contact Rep AI support |
Validation Rules
Product Validation:
Title: Maximum 500 characters
Description: Maximum 50KB
Variants: Maximum 1000 per product
Tags: Maximum 50 tags, each maximum 100 characters
Meta-fields: Maximum 100 per product
Request size: Maximum 5MB
Product Group Validation:
Title: Maximum 255 characters
Description: Maximum 10KB
Products: Maximum 10,000 per group
Handle: Maximum 255 characters
Meta-field Validation:
Key: Alphanumeric characters, dots, underscores, hyphens only
Key: Cannot start or end with special characters
Key: Maximum 255 characters
Rate Limits
Products/Groups: 100 requests per minute
Orders: 1000 requests per minute
GDPR: 10 requests per minute
SDK Examples
JavaScript/Node.js Example
const axios = require('axios');
const repAiClient = {
baseURL: '<https://server.hellorep.ai',>
apiKey: 'your-api-key-here',
accountKey: 'your-account-key',
async syncProduct(productData) {
try {
const response = await axios.post(
`${this.baseURL}/external/v1/products`,
{
account_key: this.accountKey,
...productData
},
{
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
}
}
);
return response.data;
} catch (error) {
console.error('Error syncing product:', error.response?.data || error.message);
throw error;
}
},
async orderCompleted(orderData) {
try {
const response = await axios.post(
`${this.baseURL}/external/v1/events/order-completed`,
{
account_key: this.accountKey,
...orderData
},
{
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
}
}
);
return response.data;
} catch (error) {
console.error('Error sending order completed:', error.response?.data || error.message);
throw error;
}
}
};
// Example usage
(async () => {
// Sync a product
await repAiClient.syncProduct({
id: 'prod_123',
title: 'Wireless Headphones',
variants: [{
id: 'var_123',
price: {
current: 199.99,
original: 249.99
},
quantity: 50
}]
});
// Send order completed event
await repAiClient.orderCompleted({
order_id: 'order_456',
customer_email: 'customer@example.com',
total_price: 199.99,
line_items: [{
product_id: 'prod_123',
variant_id: 'var_123',
quantity: 1,
price: 199.99
}]
});
})();
Python Example
import requests
import json
class RepAIClient:
def __init__(self, api_key, account_key, base_url='<https://server.hellorep.ai'):>
self.api_key = api_key
self.account_key = account_key
self.base_url = base_url
self.headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
def sync_product(self, product_data):
"""Sync a product to Rep AI"""
url = f'{self.base_url}/external/v1/products'
payload = {
'account_key': self.account_key,
**product_data
}
response = requests.post(url, headers=self.headers, json=payload)
response.raise_for_status()
return response.json()
def order_completed(self, order_data):
"""Send order completed event"""
url = f'{self.base_url}/external/v1/events/order-completed'
payload = {
'account_key': self.account_key,
**order_data
}
response = requests.post(url, headers=self.headers, json=payload)
response.raise_for_status()
return response.json()
# Example usage
client = RepAIClient('your-api-key', 'your-account-key')
# Sync product
product_response = client.sync_product({
'id': 'prod_123',
'title': 'Wireless Headphones',
'variants': [{
'id': 'var_123',
'price': {
'current': 199.99,
'original': 249.99
},
'quantity': 50
}]
})
print(f"Product synced: {product_response}")
cURL Examples
# Sync a product
curl -X POST <https://server.hellorep.ai/external/v1/products> \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_key": "your-account-key",
"id": "prod_123",
"title": "Wireless Headphones",
"variants": [{
"id": "var_123",
"price": {
"current": 199.99,
"original": 249.99
},
"quantity": 50
}]
}'
# Send order completed event
curl -X POST <https://api.hellorep.ai/external/v1/events/order-completed> \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_key": "your-account-key",
"order_id": "order_456",
"customer_email": "customer@example.com",
"total_price": 199.99,
"line_items": [{
"product_id": "prod_123",
"variant_id": "var_123",
"quantity": 1,
"price": 199.99
}]
}'
Best Practices
1. Data Synchronization
Incremental Updates: Only sync changed products/collections to reduce API calls
Batch Operations: Group related operations when possible
Error Handling: Implement retry logic with exponential backoff
Validation: Validate data before sending to avoid errors
2. Order Events
Real-time Events: Send order events immediately after completion
Include Session ID: Always include
rep_session_idwhen available for better attributionComplete Data: Provide as much order detail as possible for accurate analytics
3. Performance Optimization
Rate Limiting: Respect rate limits to avoid throttling
Caching: Cache API responses when appropriate
Monitoring: Monitor API response times and error rates
Async Processing: Use asynchronous processing for non-critical operations
4. Security
API Key Protection: Never expose API keys in client-side code
HTTPS Only: Always use HTTPS for API requests
Data Validation: Validate and sanitize all data before sending
Error Logging: Log errors without exposing sensitive information
Support and Resources
Getting Help
Documentation: This API specification
Support Email: support@hellorep.ai
Status Page: https://status.hellorep.ai
Useful Links
Rep AI Dashboard: https://app.hellorep.ai