Webhooks: List Orders
Overview
The List Orders webhook allows Talk2sync to retrieve your complete order history. Talk2sync will periodically request your orders endpoint to synchronize sales order data including customer information, order items, shipments, and order status.
Endpoint Requirements
You must create a GET endpoint that accepts pagination and sorting parameters from Talk2sync.
Request Format
Talk2sync will send GET requests to your configured orders endpoint with the following parameters:
Numeric Offset Pagination (Recommended)
GET https://www.example.com/your/endpoint/url?offset=0&sortorder=desc&jobid=123
T2SKey: {{API_KEY}}
Cursor-Based Pagination (Alternative)
If numeric offset pagination is not feasible for your system, you can implement cursor-based pagination:
GET https://www.example.com/your/endpoint/url?next=YXNkaWhhc3BvZGhpYXM&sortorder=desc&jobid=123
T2SKey: {{API_KEY}}
Request Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
offset | integer | Starting position for numeric pagination (0-based) | If using numeric pagination |
next | string | Base64-encoded cursor for cursor-based pagination | If using cursor pagination |
sortorder | string | Sort direction: asc (ascending) or desc (descending) | ✓ Yes |
jobid | integer | Unique identifier for this sync job (for tracking) | ✓ Yes |
T2SKey | header | Your security key provided by Talk2sync | ✓ Yes |
Authentication
The security key must be included in the T2SKey header:
T2SKey: your_generated_key_here
Response Format
Your endpoint must return a JSON response with the following structure:
{
"paging": {
"pageSize": 20,
"itemsTotal": 1,
"offset": 0
},
"orders": [
{
"_id": "75554554546",
"orderid": "75554554546",
"last_updated": 1517360038797,
"status": "paid",
"dateCreated": "",
"dateClosed": "",
"total": {
"amount": 350,
"currency": "USD"
},
"orderItems": [
{
"id": "7778545",
"variation_id": "0",
"quantity": 1,
"unitPrice": 350,
"currencyId": "USD"
}
],
"buyer": {
"id": "4578889",
"email": "testbuyer@example.com",
"phone": "88888888",
"firstName": "John",
"lastName": "Doe",
"billingaddress": {
"addressline": "",
"zipcode": "",
"city": "",
"state": "",
"country": ""
},
"shipmentaddress": {
"addressline": "",
"zipcode": "",
"city": "",
"state": "",
"country": ""
}
},
"shipments": [
{
"id": "123",
"shiptracknum": "TRK-1203912",
"shipitems": ["4578889"],
"shiptype": "Fedex",
"shipstatus": "shipping"
}
],
"rating": 2.5,
"feedback": "",
"messages": [
{
"message_id": "",
"date_created": 0,
"from": "",
"message": ""
}
]
}
]
}
Response Structure
Paging Object
| Field | Type | Description |
|---|---|---|
pageSize | integer | Number of items returned in this page |
itemsTotal | integer | Total number of orders in your system |
offset | integer | Current offset position (only for numeric pagination) |
next | string | Base64-encoded cursor for the next page (only for cursor pagination) |
Order Object
| Field | Type | Description |
|---|---|---|
_id | string | Unique order identifier (required) |
orderid | string | Order number/ID (human-readable) |
last_updated | integer | Unix timestamp (milliseconds) of last modification |
status | string | Order status (e.g., "paid", "pending", "shipped", "delivered", "cancelled") |
dateCreated | string | ISO 8601 date when order was created |
dateClosed | string | ISO 8601 date when order was closed/completed |
total | object | Total order amount and currency |
orderItems | array | Array of items in the order |
buyer | object | Buyer/customer information |
shipments | array | Array of shipment information |
rating | number | Order rating (0.0 - 5.0) |
feedback | string | Customer feedback/review |
messages | array | Array of customer messages/communications |
Total Object
| Field | Type | Description |
|---|---|---|
amount | number | Total order amount |
currency | string | ISO 4217 currency code (e.g., "USD", "MXN") |
Order Item Object
| Field | Type | Description |
|---|---|---|
id | string | Item/product identifier |
variation_id | string | Product variation ID |
quantity | integer | Quantity ordered |
unitPrice | number | Price per unit |
currencyId | string | Currency code |
Buyer Object
| Field | Type | Description |
|---|---|---|
id | string | Unique buyer identifier |
email | string | Buyer email address |
phone | string | Buyer phone number |
firstName | string | Buyer first name |
lastName | string | Buyer last name |
billingaddress | object | Billing address information |
shipmentaddress | object | Shipping address information |
Address Object (Billing & Shipment)
| Field | Type | Description |
|---|---|---|
addressline | string | Street address |
zipcode | string | Postal/ZIP code |
city | string | City name |
state | string | State/Province |
country | string | Country name or code |
Shipment Object
| Field | Type | Description |
|---|---|---|
id | string | Unique shipment identifier |
shiptracknum | string | Tracking number |
shipitems | array | Array of item IDs included in shipment |
shiptype | string | Carrier type (e.g., "Fedex", "UPS", "DHL") |
shipstatus | string | Shipment status (e.g., "pending", "shipping", "delivered") |
Message Object
| Field | Type | Description |
|---|---|---|
message_id | string | Unique message identifier |
date_created | integer | Unix timestamp when message was created |
from | string | Sender identifier (buyer, seller, or system) |
message | string | Message content |
Implementation Example (Node.js/Express)
app.get('/api/orders', (req, res) => {
const { offset = 0, next, sortorder = 'desc', jobid } = req.query;
const apiKey = req.headers['t2skey'];
// Validate API key
if (apiKey !== process.env.TALK2SYNC_KEY) {
return res.status(401).json({ error: 'Unauthorized' });
}
try {
// Fetch orders from your database
const allOrders = fetchOrdersFromDatabase(sortorder);
// Implement pagination (numeric offset example)
const pageSize = 20;
const startIndex = parseInt(offset) || 0;
const paginatedOrders = allOrders.slice(startIndex, startIndex + pageSize);
// Build response
const response = {
paging: {
pageSize: paginatedOrders.length,
itemsTotal: allOrders.length,
offset: startIndex
},
orders: paginatedOrders.map(order => ({
_id: order.id,
orderid: order.orderNumber,
last_updated: new Date(order.updatedAt).getTime(),
status: order.status,
dateCreated: order.createdAt,
dateClosed: order.closedAt || "",
total: {
amount: order.totalAmount,
currency: order.currency || "USD"
},
orderItems: order.items.map(item => ({
id: item.productId,
variation_id: item.variationId || "0",
quantity: item.quantity,
unitPrice: item.price,
currencyId: order.currency || "USD"
})),
buyer: {
id: order.buyerId,
email: order.buyerEmail,
phone: order.buyerPhone || "",
firstName: order.buyerFirstName || "",
lastName: order.buyerLastName || "",
billingaddress: {
addressline: order.billingAddress?.street || "",
zipcode: order.billingAddress?.zipcode || "",
city: order.billingAddress?.city || "",
state: order.billingAddress?.state || "",
country: order.billingAddress?.country || ""
},
shipmentaddress: {
addressline: order.shippingAddress?.street || "",
zipcode: order.shippingAddress?.zipcode || "",
city: order.shippingAddress?.city || "",
state: order.shippingAddress?.state || "",
country: order.shippingAddress?.country || ""
}
},
shipments: order.shipments?.map(ship => ({
id: ship.id,
shiptracknum: ship.trackingNumber || "",
shipitems: ship.itemIds || [],
shiptype: ship.carrier || "",
shipstatus: ship.status || "pending"
})) || [],
rating: order.rating || 0,
feedback: order.review || "",
messages: order.messages?.map(msg => ({
message_id: msg.id || "",
date_created: new Date(msg.createdAt).getTime(),
from: msg.sender || "",
message: msg.content || ""
})) || []
}))
};
res.json(response);
} catch (error) {
console.error('Error fetching orders:', error);
res.status(500).json({ error: 'Internal Server Error' });
}
});
Response Status Codes
| Status | Meaning | Action |
|---|---|---|
200 OK | Orders retrieved successfully | Talk2sync processes the data |
400 Bad Request | Invalid parameters | Check your request parameters |
401 Unauthorized | Invalid or missing API key | Verify your security key |
500 Internal Server Error | Server error | Check your server logs |
Pagination Guidelines
Numeric Offset Strategy
Best for: Small to medium datasets (< 100,000 orders)
- Return items from
offsettooffset + pageSize - Increment
offsetbypageSizefor each request - Include
offsetin the paging response
Cursor-Based Strategy
Best for: Large datasets or frequently changing data
- Encode the next page's starting point as a base64 cursor
- Return the cursor in the response as
next - Use the
nextparameter for subsequent requests - More efficient for large datasets
Order Status Values
Common order status values include:
| Status | Description |
|---|---|
pending | Order received, awaiting payment |
paid | Payment confirmed |
processing | Order is being prepared |
shipped | Order has been shipped |
delivered | Order delivered to customer |
cancelled | Order was cancelled |
refunded | Payment has been refunded |
Note: Use status values that match your system. Talk2sync will store whatever values you return.
Timing and Frequency
- Talk2sync will request orders according to the synchronization schedule configured in your connection settings
- The
jobidparameter helps you track which sync job initiated each request - Each request should be processed and return within 1 minute
Handling Order Updates
When orders are updated:
- Update the
last_updatedtimestamp to the current time - Ensure the order status reflects the latest state
- Include all shipments and messages up to the current time
- Return the updated order in the next sync
Best Practices
✓ Do:
- Return data sorted consistently (use
sortorderparameter) - Include accurate
last_updatedtimestamps - Validate the API key on every request
- Implement pagination to handle large order lists
- Use ISO 8601 format for date fields
- Include complete buyer and address information when available
- Maintain shipment tracking information
✗ Don't:
- Include sensitive payment information (credit card numbers)
- Return personal information beyond what's needed
- Return the same order multiple times
- Ignore the sorting parameter
- Return responses larger than 10MB per page
- Include internal system notes or private comments
Data Mapping Best Practices
Dates
Use one of these formats consistently:
- ISO 8601:
2024-01-15T10:30:00Z(recommended) - Empty string:
""(if date not available)
Currencies
Always use ISO 4217 3-letter currency codes:
USD(US Dollar)MXN(Mexican Peso)EUR(Euro)GBP(British Pound)
Status Fields
Keep status values consistent and predictable. Examples:
- Order Status: pending, paid, processing, shipped, delivered, cancelled, refunded
- Shipment Status: pending, shipping, delivered, returned, lost
- Buyer Status: active, inactive, blocked
Related Webhooks
Related Documentation
- Quick Start: Generate Keys
- Webhooks Overview
- List Products (similar pagination approach)