Actions: Pull and Push

Actions are the fundamental operations in Retrieve. Every integration uses two types of actions: Pull (to get data) and Push (to send data). Think of them like breathing - you breathe in (pull) and breathe out (push).

What is a Pull Action?

A Pull action retrieves data from a system. It's like asking a question and getting an answer back.

Pull Action Examples

Example 1: Pull Customers from Shopify

Get a list of all customers who signed up in the last 24 hours:

• What you're asking: "Show me new customers"
• What you get back: Customer names, emails, phone numbers, addresses
• What happens next: This data moves to the next step in your workflow

Example 2: Pull Orders from WooCommerce

Retrieve all orders that need to be fulfilled:

• What you're asking: "Show me orders waiting to be shipped"
• What you get back: Order numbers, items, customer details, shipping addresses
• What happens next: Send this data to your warehouse system

Example 3: Pull Products from Odoo

Get your product catalog with current inventory levels:

• What you're asking: "What products do I have in stock?"
• What you get back: Product names, SKUs, prices, quantities, descriptions
• What happens next: Update your online store with this information

What is a Push Action?

A Push action sends data to a system. It's like making a delivery.

Push Action Examples

Example 1: Push Customers to Mailchimp

Add new customers to your email marketing list:

• What you're sending: Customer email addresses and names
• Where it goes: Mailchimp subscriber list
• What happens: Customers receive your welcome email campaign

Example 2: Push Orders to NetSuite

Create sales orders in your accounting system:

• What you're sending: Order details, line items, customer information
• Where it goes: NetSuite ERP system
• What happens: Your accounting team can process and invoice the order

Example 3: Push Inventory Updates to Shopify

Update product stock levels on your online store:

• What you're sending: Product SKUs and new quantities
• Where it goes: Shopify inventory system
• What happens: Customers see accurate stock availability

Pull and Push Working Together

Most integrations use both actions in sequence. Data flows from one system to another:

Complete Workflow Example

Scenario: Sync new Shopify orders to your warehouse system

Action Configuration

When you set up an action, you configure what data to request or send:

Pull Action Configuration

{
  "node-1": {
    "action": "pull",
    "entity": "orders",
    "package": "@imagination-media/integrator-shopify",
    "config": {
      "created_at_min": "2024-01-01T00:00:00Z",
      "status": "any",
      "limit": 250
    }
  }
}

What this means:

• action: "pull" - We're getting data from Shopify
• entity: "orders" - We want orders (not customers or products)
• created_at_min - Only orders from the last 24 hours
• status: "any" - All orders regardless of status
• limit: 250 - Get up to 250 orders per request

Push Action Configuration

{
  "node-2": {
    "action": "push",
    "entity": "sales_orders",
    "package": "@imagination-media/integrator-netsuite",
    "config": {
      "update_existing": true,
      "match_field": "externalId"
    }
  }
}

What this means:

• action: "push" - We're sending data to NetSuite
• entity: "sales_orders" - Creating sales orders
• update_existing: true - Update if order already exists
• match_field: "externalId" - Match on this field to find existing orders

Common Pull/Push Patterns

Pattern 1: One-Way Sync

Data flows in one direction only.

Use case: Send all new e-commerce orders to your ERP system

Pattern 2: Two-Way Sync

Data flows in both directions to keep systems in sync.

Use case: Keep product inventory synchronized between warehouse and online store

Pattern 3: Hub and Spoke

Pull data from one central system and push to multiple destinations.

Use case: Distribute product catalog from master system to all sales channels

Pattern 4: Data Aggregation

Pull data from multiple sources and push to one destination.

Use case: Collect orders from multiple marketplaces into one fulfillment system

Best Practices

For Pull Actions

• Use filters: Only pull data you need (e.g., orders from last 24 hours, not all orders ever)
• Set appropriate limits: Don't request more records than you can process
• Use pagination: Handle large datasets in smaller chunks
• Track what you've pulled: Avoid processing the same data twice
• Schedule wisely: Pull frequently for time-sensitive data, less often for static data

For Push Actions

• Validate before pushing: Check data is complete and correctly formatted
• Handle duplicates: Use unique identifiers to prevent creating duplicate records
• Implement retry logic: Retry failed pushes with exponential backoff
• Batch when possible: Send multiple records in one request for efficiency
• Confirm success: Verify the destination system accepted the data

Available Integration Packages

Retrieve supports pull and push actions for many platforms:

Troubleshooting

Pull Action Issues

Push Action Issues

Next Steps

• Field Mapping - Learn how to transform data between pull and push
• Understanding Workflows - See how actions connect in workflows
• Rewrite Functions - Add custom logic to your actions
• Integration Packages - Browse all available platforms