Ecomdrop Integration

Overview

The Ecomdrop integration enables automated order processing through intelligent workflows. When orders are created in your Shopify store, they are automatically sent to Ecomdrop for processing, and your orders are updated with tags based on the processing status.

Getting Your API Key

To connect your store with Ecomdrop, you’ll need an API access token from your Ecomdrop account.

Access Ecomdrop Panel

Navigate to API Settings

Go to your account settings and locate the API section

Generate Access Token

Create a new API access token or copy your existing token. This will be your X-ACCESS-TOKEN.

Save the Token

Keep this token secure - you’ll need it to configure the app

Never share your API token publicly or commit it to version control. Treat it like a password.

Configuring the Integration

Open App Configuration

In your Shopify admin, navigate to Apps > Ecomdrop IA Connector > Configuration

Enter API Key

Paste your Ecomdrop API token in the “Ecomdrop API Key” field

Select Flows

Choose which Ecomdrop flows to trigger for:

New orders (ORDERS_CREATE webhook)
Abandoned checkouts (CHECKOUTS_CREATE webhook)

Save Configuration

Click “Save” to activate the integration

Available Flows

The app fetches your available flows from Ecomdrop and displays them for selection:

GET https://panel.ecomdrop.app/api/accounts/flows
Headers:
  X-ACCESS-TOKEN: your_api_key
  accept: application/json

Response Format

[
  {
    "id": "flow_123",
    "name": "Process Order",
    "description": "Automated order processing workflow",
    "status": "active"
  }
]

Triggering Workflows

Automatic Triggering

When configured, the app automatically triggers your selected Ecomdrop flows when:

New Order Created - Shopify sends ORDERS_CREATE webhook
Checkout Abandoned - Shopify sends CHECKOUTS_CREATE webhook

The app sends comprehensive order data to your Ecomdrop flow:

{
  "orderId": "gid://shopify/Order/1234567890",
  "orderName": "#1001",
  "orderNumber": 1001,
  "createdAt": "2024-03-04T12:00:00Z",
  "totalPrice": "99.99",
  "currency": "USD",
  "financialStatus": "PAID",
  "fulfillmentStatus": "UNFULFILLED",
  "lineItems": [
    {
      "id": "gid://shopify/LineItem/123",
      "title": "Product Name",
      "quantity": 2,
      "price": "49.99",
      "sku": "PROD-001",
      "variantId": "gid://shopify/ProductVariant/456"
    }
  ],
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890"
  },
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "province": "NY",
    "country": "United States",
    "zip": "10001",
    "phone": "+1234567890"
  },
  "shop": "yourstore.myshopify.com",
  "eventType": "order_created",
  "callbackUrl": "https://your-app.com/api/ecomdrop/callback",
  "callbackApiKey": "your_api_key"
}

Manual Triggering via API

You can also trigger flows programmatically:

POST https://panel.ecomdrop.app/api/flows/{flowId}/trigger
Headers:
  X-ACCESS-TOKEN: your_api_key
  Content-Type: application/json
  
Body:
{
  "orderId": "gid://shopify/Order/123",
  "orderName": "#1001",
  // ... additional order data
}

Callback System

How It Works

Ecomdrop processes orders asynchronously to avoid timeouts. When processing completes, Ecomdrop calls back to update your order:

Order Created

Shopify webhook triggers and sends order data to Ecomdrop

Ecomdrop Processes

Your flow processes the order (may take minutes)

Callback Sent

Ecomdrop POSTs results to your callback URL

Order Updated

App updates Shopify order with status tags

Callback Endpoint

POST /api/ecomdrop/callback

Expected Payload

Ecomdrop should send this payload when processing completes:

{
  "orderName": "#1001",
  "shop": "yourstore.myshopify.com",
  "apiKey": "your_ecomdrop_api_key",
  "status": "success",
  "tag": "ecomdrop-processed"
}

Callback Parameters

apiKey

string

required

Your Ecomdrop API key for authentication

orderName

string

required

Order identifier in format #1001 (this is what Ecomdrop receives)

orderId

string

Alternative: GraphQL order ID like gid://shopify/Order/123

shop

string

Store domain (e.g., yourstore.myshopify.com). Optional if API key identifies the shop.

tag

string

Single tag to add to the order

Status Tag Mapping

When using the status field, tags are automatically assigned:

Status	Tag Added
`success`	`ecomdrop-processed`
`completed`	`ecomdrop-completed`
`pending`	`ecomdrop-pending`
`error`	`ecomdrop-error`
`failed`	`ecomdrop-error`

Response Format

{
  "success": true,
  "message": "Tags added successfully: ecomdrop-processed",
  "orderId": "gid://shopify/Order/1234567890",
  "tags": ["ecomdrop-processed"]
}

Testing the Callback

Using cURL

curl -X POST https://your-app-url.com/api/ecomdrop/callback \
  -H "Content-Type: application/json" \
  -d '{
    "orderName": "#1001",
    "apiKey": "your_ecomdrop_api_key",
    "status": "success",
    "tag": "test-processed"
  }'

Using Postman

Create POST Request

Method: POST
URL: https://your-app-url.com/api/ecomdrop/callback

Set Headers

Content-Type: application/json

Add Body

{
  "orderName": "#1001",
  "apiKey": "your_api_key",
  "status": "success"
}

Send Request

Verify the order in Shopify receives the tag

Authentication & Security

The callback endpoint validates:

API Key Match - The provided API key must exist in the database
Shop Verification - API key must belong to the correct shop
Session Active - Shopify app must be installed on the shop

The endpoint returns HTTP 200 even for errors to prevent Shopify from retrying failed webhooks. Check the response body for actual status.

Error Handling

Common Errors

Invalid API key (401)

Cause: The API key doesn’t match any configured shop
Solution: Verify the API key in your app configuration matches what Ecomdrop is sending

Order not found (404)

Cause: The order name doesn’t exist in the shop
Solution: Ensure the orderName format is correct (e.g., #1001)

No active session (404)

Cause: App is not installed on the shop
Solution: Reinstall the app on the Shopify store

Protected data error (403)

Cause: App not approved for protected customer data access
Solution: This will work after app publication and Shopify approval

Rate Limiting

The app implements a 1-minute cache for flow listings to prevent rate limiting:

// Flows are cached for 60 seconds
const CACHE_DURATION = 60000; // 1 minute

Flows are automatically refreshed when you navigate to the configuration page after the cache expires.

Best Practices

Use Callbacks - Always configure callback URLs to handle async processing
Monitor Tags - Set up Shopify Flow rules to act on Ecomdrop tags
Test Thoroughly - Use the test endpoints before going live
Handle Errors - Monitor for ecomdrop-error tags and investigate
Secure API Keys - Rotate API keys periodically for security

Code Reference

Integration code location in source:

API Client: app/lib/ecomdrop.api.server.ts:31
Callback Handler: app/routes/api.ecomdrop.callback.tsx:22
Webhook Handler: app/routes/webhooks.orders.create.tsx:7

Support

If you encounter issues:

Check server logs for detailed error messages
Verify API key is correctly configured in both systems
Ensure callback URL is accessible from Ecomdrop servers
Test with the manual callback endpoints first

Overview

Getting Started

Core Features

Integrations

Configuration

Deployment

Overview

Getting Your API Key

Configuring the Integration

Available Flows

Response Format

Triggering Workflows

Automatic Triggering

Manual Triggering via API

Callback System

How It Works

Callback Endpoint

Expected Payload

Callback Parameters

Status Tag Mapping

Response Format

Testing the Callback

Using cURL

Using Postman

Authentication & Security

Error Handling

Common Errors

Rate Limiting

Best Practices

Code Reference

Support

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

Integrations

Configuration

Deployment

Documentation Index

​Overview

​Getting Your API Key

​Configuring the Integration

​Available Flows

​Response Format

​Triggering Workflows

​Automatic Triggering

​Manual Triggering via API

​Callback System

​How It Works

​Callback Endpoint

​Expected Payload

​Callback Parameters

​Status Tag Mapping

​Response Format

​Testing the Callback

​Using cURL

​Using Postman

​Authentication & Security

​Error Handling

​Common Errors

​Rate Limiting

​Best Practices

​Code Reference

​Support

Build docs developers (and LLMs) love

Overview

Getting Your API Key

Configuring the Integration

Available Flows

Response Format

Triggering Workflows

Automatic Triggering

Manual Triggering via API

Callback System

How It Works

Callback Endpoint

Expected Payload

Callback Parameters

Status Tag Mapping

Response Format

Testing the Callback

Using cURL

Using Postman

Authentication & Security

Error Handling

Common Errors

Rate Limiting

Best Practices

Code Reference

Support