DocumentationDocumentation
Talk2Sync Documentation
User Documentation
Connector APIs
  • English
  • Español
Talk2Sync Documentation
User Documentation
Connector APIs
  • English
  • Español
  • User Guide Portal & API Documentation
  • User-documentation

    • User Documentation
    • Guide

      • User Guide: Introduction
      • Core Concepts
    • Talk2sync

      • Connection Buttons
      • Color Coding System
      • Issues and Alerts
      • Command Filters
      • Deleted Information Still Appears: How to Remove It
      • Deletions
    • Conexiones

      • Connection Settings
    • Fields

      • Time Based Sync
      • Data Governance
      • Special and Extra Fields
    • Productos

      • Product Fields
      • Equivalences
      • Product Search
      • Link / Unlink Products
    • Ventas

      • Fields
      • Equivalences
      • Sales Search
      • No SKU (Missing SKU)
    • Reports

      • Product Export
      • Sales Report
    • Faq

      • Amazon

        • Amazon Barcode Requirements
        • Amazon Catalog Discrepancies and ASIN Mismatches
        • Amazon Manufacturer Requirements
        • New ASIN Creation Errors and Invalid Attribute Values
        • Talk2sync, SKUs, and Product Identifiers
        • Amazon Variation Templates
      • Mercadolibre

        • Mercado Libre Official Stores
        • Mercado Libre Locations and Geographic Attributes
        • Mercado Libre Pick-up in Store
        • Mercado Libre Extra Attributes
        • Mercado Libre Image Processing and Synchronization
        • Mercado Libre Seller Unable to List Error
      • Linio

        • Linio Brand Not Registered Error
        • Linio Physical Dimensions and Weight Requirements
  • Connector APIs

    • Connector APIs
    • Quick-start

      • Introduction & Requirements
      • Add Connection
      • Configure Connection
      • Generate Keys
      • Test Your Integration
    • Webhooks

      • Webhooks API
      • Catalog

        • Webhooks: List Products
        • Webhooks: List Product by ID
        • Webhooks: Add/Update Product
      • Sales

        • Webhooks: List Orders
        • List Order by ID
        • Add/Update Order
    • Reverse-connections

      • Reverse Connections
      • Implementation-states

        • Implementation
        • Query Implementation: Products and Orders
        • Store Implementation: Products and Orders
        • Sleep and Timeouts
      • Protocol

        • Protocol
        • Overview
        • Product Upload
        • Order Upload
        • Product Download
        • Order Download
      • Rest-calls

        • REST Calls
        • Fetching-changes

          • Fetching Changes REST Calls
          • Ask if Fetching
          • Catalog

            • Push Products Page
            • Set Finish Product Pushes
          • Sales

            • Push Orders Page
            • Set Finish Order Pushes
            • Set Finish All Pushes
        • Pulling-changes

          • Pulling Changes REST Calls
          • Ask if Pulling
          • Catalog

            • Get Next Product to Pull
            • Pull Products Page
            • Notify Product Storage Success
            • Notify Product Storage Failure
            • Set Finish Product Download
          • Sales

            • Get Next Order to Pull
            • Pull Orders Page
            • Notify Order Storage Success
            • Notify Order Storage Failure
            • Set Finish Order Download
            • Transact Finish Pull

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

ParameterTypeDescriptionRequired
offsetintegerStarting position for numeric pagination (0-based)If using numeric pagination
nextstringBase64-encoded cursor for cursor-based paginationIf using cursor pagination
sortorderstringSort direction: asc (ascending) or desc (descending)✓ Yes
jobidintegerUnique identifier for this sync job (for tracking)✓ Yes
T2SKeyheaderYour 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

FieldTypeDescription
pageSizeintegerNumber of items returned in this page
itemsTotalintegerTotal number of orders in your system
offsetintegerCurrent offset position (only for numeric pagination)
nextstringBase64-encoded cursor for the next page (only for cursor pagination)

Order Object

FieldTypeDescription
_idstringUnique order identifier (required)
orderidstringOrder number/ID (human-readable)
last_updatedintegerUnix timestamp (milliseconds) of last modification
statusstringOrder status (e.g., "paid", "pending", "shipped", "delivered", "cancelled")
dateCreatedstringISO 8601 date when order was created
dateClosedstringISO 8601 date when order was closed/completed
totalobjectTotal order amount and currency
orderItemsarrayArray of items in the order
buyerobjectBuyer/customer information
shipmentsarrayArray of shipment information
ratingnumberOrder rating (0.0 - 5.0)
feedbackstringCustomer feedback/review
messagesarrayArray of customer messages/communications

Total Object

FieldTypeDescription
amountnumberTotal order amount
currencystringISO 4217 currency code (e.g., "USD", "MXN")

Order Item Object

FieldTypeDescription
idstringItem/product identifier
variation_idstringProduct variation ID
quantityintegerQuantity ordered
unitPricenumberPrice per unit
currencyIdstringCurrency code

Buyer Object

FieldTypeDescription
idstringUnique buyer identifier
emailstringBuyer email address
phonestringBuyer phone number
firstNamestringBuyer first name
lastNamestringBuyer last name
billingaddressobjectBilling address information
shipmentaddressobjectShipping address information

Address Object (Billing & Shipment)

FieldTypeDescription
addresslinestringStreet address
zipcodestringPostal/ZIP code
citystringCity name
statestringState/Province
countrystringCountry name or code

Shipment Object

FieldTypeDescription
idstringUnique shipment identifier
shiptracknumstringTracking number
shipitemsarrayArray of item IDs included in shipment
shiptypestringCarrier type (e.g., "Fedex", "UPS", "DHL")
shipstatusstringShipment status (e.g., "pending", "shipping", "delivered")

Message Object

FieldTypeDescription
message_idstringUnique message identifier
date_createdintegerUnix timestamp when message was created
fromstringSender identifier (buyer, seller, or system)
messagestringMessage 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

StatusMeaningAction
200 OKOrders retrieved successfullyTalk2sync processes the data
400 Bad RequestInvalid parametersCheck your request parameters
401 UnauthorizedInvalid or missing API keyVerify your security key
500 Internal Server ErrorServer errorCheck your server logs

Pagination Guidelines

Numeric Offset Strategy

Best for: Small to medium datasets (< 100,000 orders)

  • Return items from offset to offset + pageSize
  • Increment offset by pageSize for each request
  • Include offset in 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 next parameter for subsequent requests
  • More efficient for large datasets

Order Status Values

Common order status values include:

StatusDescription
pendingOrder received, awaiting payment
paidPayment confirmed
processingOrder is being prepared
shippedOrder has been shipped
deliveredOrder delivered to customer
cancelledOrder was cancelled
refundedPayment 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 jobid parameter 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_updated timestamp 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 sortorder parameter)
  • Include accurate last_updated timestamps
  • 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

  • List Order by ID
  • Add/Update Order

Related Documentation

  • Quick Start: Generate Keys
  • Webhooks Overview
  • List Products (similar pagination approach)
Last Updated: 8/28/26, 12:58 AM
Next
List Order by ID