Order Import Automations

What Is an Order Import?

An order import automation pulls order data from an external system into SureDone. The most common use cases are:

• Dropship purchase orders -- A retail partner sends you orders via their FTP server or API.
• Tracking updates -- Your fulfillment provider uploads tracking numbers and shipping status to an SFTP folder.
• Cross-platform order sync -- Pull orders from a system that is not natively integrated with SureDone.
• Order enrichment -- Fetch additional data (vendor assignments, cost lookups) from an API and update existing orders.

Order imports follow the same connect-download-map-transform-import pattern as product imports, but with additional structure to handle order line items, shipments, and refunds.

Order Structure

Orders in SureDone are more complex than products. A single order contains multiple layers of data:

• Base order fields -- Order-level data like oid (order ID), status, total, email, shipping address fields (shippingfirstname, shippinglastname, shippingstreet1, shippingcity, shippingstateprovince, shippingpostalcode, shippingcountry), billing address, payment info, and dates.
• Line items -- Each order has one or more items with fields like sku, quantity, price, title, and itemstatus. Each line item also has an itemid that uniquely identifies it within the order.
• Shipments (optional) -- Tracking numbers, carriers, ship dates, and shipping status.
• Refunds (optional) -- Refund amounts, reasons, and associated items.

When importing, you map vendor fields to each of these layers using field_map for the base order and items, plus field_run with special placeholders for the other components.

Import Modes

Order imports use boolean values for create, update, and remove:

At least one must be set. The most common combination is "update": true for tracking imports and status updates, or "create": true combined with "update": true for full order sync.

Order Item Identifier

The order_item_identifier config tells the engine which field to use when matching incoming line items to existing items within an order. It defaults to sku.

If your vendor uses a different identifier for line items (like an internal item ID), you can change this:

"order_item_identifier": "vendoritemid"

This is separate from the order-level identifier (which defaults to oid for orders) and specifically controls how individual items within an order are matched.

Identifier for Orders

Just like product imports, the identifier config controls how orders are matched. It defaults to oid (order ID). If your vendor uses their own order number, map it to an appropriate SureDone field and set that as the identifier:

"identifier": "oid",
"field_run": {
    "oid": "CustomerPONumber"
}

Multi-Object Field Mapping

Orders require you to map fields across different object types. The field_map and field_run configs handle the base order and item fields, while special placeholders_* arrays tell the engine which fields belong to sub-objects:

placeholders_items -- Fields from field_run that should be treated as order item fields:

"field_run": {
    "oid": "$.orders.*.oid",
    "itemid": "$.orders.*.items.*.itemid",
    "vendor": "$.orders.*.items.*.vendor"
},
"placeholders_items": ["itemid", "vendor"]

placeholders_shipments -- Fields that map to shipment data (tracking, carrier, ship date).

placeholders_refunds -- Fields that map to refund data.

These placeholders ensure the engine processes each field at the correct level -- order, item, shipment, or refund -- rather than trying to apply item-level data at the order level.

Order-Specific Fields

Here are the most commonly mapped order fields:

Inventory Sync

The orders_sync_inventory config is a boolean that defaults to false. When set to true, the engine adjusts the stock of matching products in SureDone as orders are imported. This is useful when importing orders from an external system and you need SureDone's inventory to reflect those sales:

"orders_sync_inventory": true

Address Validation

Set orders_address_validation to true to validate shipping addresses during import. This uses SureDone's address validation service to check that addresses are real and deliverable.

Date Filtering

Use orders_start_date and orders_end_date to limit which orders are processed. These accept any valid PHP datetime string:

"orders_start_date": "-7 days",
"orders_end_date": "now"

This only processes orders from the last 7 days. These configs are particularly useful with API-based imports where you want to avoid re-processing old orders.

EDI Orders

For partners that communicate via EDI (Electronic Data Interchange), the Automation Engine supports EDI-specific configurations:

• edi_spec -- Specifies the EDI document type: 850 (purchase orders), 856 (advance ship notice), or 997 (acknowledgment).
• edi_export_path -- Where to send EDI acknowledgments.
• edi_sender_id and edi_receiver_id -- ISA header identifiers for EDI documents.

EDI is an advanced integration topic. If your partner requires EDI, contact SureDone support for setup assistance.

Using Search to Scope Updates

The search config on order imports works the same as on product imports -- it limits which existing orders are eligible for updates. For example, if you are importing tracking numbers, you might only want to update orders that are currently in "ORDERED" status:

"search": "status:=ORDERED"

Orders that do not match the search are skipped, even if they match on the identifier.

Complete Example: Dropship Order Import from SFTP CSV

This automation imports new dropship purchase orders from a retail partner who drops CSV files on their SFTP server.

{
    "name": "PO Import from RetailCo",
    "vendor": "RetailCo",
    "active": true,
    "schedule": "*/15 * * * *",
    "type": "orders",
    "action": "import",
    "connection": {
        "type": "sftp",
        "address": "sftp.retailco.com",
        "username": "{{sftp_user}}",
        "password": "{{sftp_pass}}",
        "path": "/outbound/orders",
        "port": 22
    },
    "file_configs": [
        {
            "regex": "/PO_(.*)\\.csv/",
            "identifier": "oid",
            "create": true,
            "update": true,
            "field_map": {
                "oid": "PO_Number",
                "sku": "Item_SKU",
                "quantity": "Qty",
                "price": "Unit_Price",
                "shippingfirstname": "Ship_First",
                "shippinglastname": "Ship_Last",
                "shippingstreet1": "Ship_Addr1",
                "shippingstreet2": "Ship_Addr2",
                "shippingcity": "Ship_City",
                "shippingstateprovince": "Ship_State",
                "shippingpostalcode": "Ship_Zip",
                "shippingcountry": "Ship_Country",
                "shippingphone": "Ship_Phone"
            },
            "value_map_default": {
                "status": "READY",
                "channel": "dropship",
                "shippingcountry": "US"
            },
            "orders_sync_inventory": true,
            "delete_remote_file": true
        }
    ],
    "parameters": [
        {
            "name": "sftp_user",
            "value": "",
            "label": "SFTP Username"
        },
        {
            "name": "sftp_pass",
            "value": "",
            "encrypted": true,
            "label": "SFTP Password"
        }
    ]
}

What this does:

• Runs every 15 minutes
• Uses a regex to match any file named PO_*.csv in the orders directory
• Creates new orders or updates existing ones based on PO_Number
• Maps shipping address, line items (SKU, quantity, price), and contact info
• Sets default values: status to "READY", channel to "dropship", country to "US"
• Syncs inventory -- decrements stock for the ordered items
• Deletes each file from the SFTP server after successful processing