Deployment Strategies

HubSpot Deploy uses two different strategies to deploy metadata: Batch and Sequential. The system automatically chooses the best strategy for each type of metadata to optimize speed and reliability.

Overview

Different types of metadata require different deployment approaches:

• Batch Strategy - Deploys multiple items at once (up to 100 at a time)
• Sequential Strategy - Deploys items one at a time

You don't need to choose which strategy to use - the system automatically selects the optimal approach for each metadata type.

Batch Strategy

What It Does

The Batch strategy groups items together and sends them to HubSpot in batches of up to 100 items per request. This is much faster than deploying items individually.

When It's Used

Batch deployment is used exclusively for creating new properties:

• Standard Object Properties (new properties for Contacts, Companies, Deals, etc.)
• Custom Object Properties (new properties for your custom objects)

How It Works

1. Groups by Object Type - Properties are grouped by their parent object (e.g., all Contact properties together)
2. Creates Batches - Each group is split into batches of 100 items
3. Deploys in Parallel - Multiple properties are created simultaneously
4. Tracks Results - Success and errors are tracked for each individual property

Example

If you're deploying 250 new Contact properties:

1. All 250 properties are grouped together (same object type)
2. Split into 3 batches: 100 + 100 + 50
3. Batch 1: 100 properties deployed → ~2 seconds
4. Batch 2: 100 properties deployed → ~2 seconds
5. Batch 3: 50 properties deployed → ~1 second
6. Total time: ~5 seconds (vs. 250+ seconds if deployed one at a time)

Benefits

• Speed - Up to 100x faster than sequential deployment
• Efficiency - Fewer API calls to HubSpot
• Reliability - Individual failures don't stop the entire batch

Limitations

• Only works for creating properties (not updates or deletes)
• Only works for properties (not other metadata types)
• Maximum 100 items per batch (HubSpot API limit)

Sequential Strategy

What It Does

The Sequential strategy deploys items one at a time, waiting for each to complete before moving to the next.

When It's Used

Sequential deployment is used for:

• All property updates (modifying existing properties)
• All other metadata types (workflows, forms, pipelines, custom objects, etc.)
• All delete operations

How It Works

1. Deploys One Item - Sends a single item to HubSpot
2. Waits for Completion - Waits for HubSpot to confirm success or failure
3. Moves to Next - Proceeds to the next item
4. Handles Errors - Retries failed items automatically

Example

If you're deploying 10 workflows:

1. Workflow 1 deployed → success → ~2 seconds
2. Workflow 2 deployed → success → ~2 seconds
3. Workflow 3 deployed → error → retry → success → ~4 seconds
4. Workflow 4 deployed → success → ~2 seconds
5. ... and so on
6. Total time: ~25 seconds

Benefits

• Reliability - Each item is confirmed before moving forward
• Error Handling - Automatic retries for failed items
• Compatibility - Works with all metadata types and operations
• Detailed Logging - Clear tracking of each item's status

Retry Logic

The Sequential strategy includes automatic retry for transient errors:

• Rate Limit Errors (429) - Waits and retries automatically
• Server Errors (500+) - Retries up to 3 times with exponential backoff
• Temporary Failures - Automatically handled without user intervention

Retry delays:

• 1st retry: 2 seconds
• 2nd retry: 4 seconds
• 3rd retry: 8 seconds

Strategy Selection

The system automatically chooses the strategy based on:

Metadata Type + Operation

Metadata Type	Operation	Strategy
Standard Object Property	Create	Batch
Custom Object Property	Create	Batch
Standard Object Property	Update	Sequential
Custom Object Property	Update	Sequential
All other types	Any	Sequential

Why This Matters

You might notice that:

• Creating 100 new properties takes only a few seconds (Batch)
• Updating 100 existing properties takes several minutes (Sequential)

This is expected behavior - HubSpot's API supports batch creation but not batch updates for properties.

Performance Comparison

Creating 100 Properties

Strategy	Time	API Calls
Batch	~5 seconds	1 call
Sequential	~200 seconds	100 calls

Batch is ~40x faster for property creation.

Deploying 50 Workflows

Strategy	Time	API Calls
Sequential	~100 seconds	50 calls

Workflows must be deployed sequentially (no batch option available).

What You See During Deployment

Batch Deployment

In the deployment logs, you'll see:

BatchStrategy: Deploying 100 items in 1 batch for contacts
BatchStrategy: Batch 1/1 - deploying 100 items
BatchStrategy: Batch 1/1 complete (success: 98, errors: 2, duration: 2341ms)

Sequential Deployment

In the deployment logs, you'll see:

SequentialStrategy: Deploying 10 items sequentially
SequentialStrategy: Item 1/10 - workflow:lead_nurture - success
SequentialStrategy: Item 2/10 - workflow:deal_followup - success
SequentialStrategy: Item 3/10 - workflow:contact_scoring - retry (429)
SequentialStrategy: Item 3/10 - workflow:contact_scoring - success

Error Handling

Batch Strategy Errors

When a batch deployment encounters errors:

• Partial Success - Some items succeed, others fail
• Individual Tracking - Each item's result is recorded separately
• No Retries - Failed items are marked as errors (you can retry manually)
• Continues - Remaining batches are still processed

Example: If 2 out of 100 properties fail in a batch, the other 98 are still created successfully.

Sequential Strategy Errors

When a sequential deployment encounters errors:

• Automatic Retry - Transient errors are retried automatically (up to 3 times)
• Continues - Deployment continues to next item after failure
• Detailed Logs - Each error is logged with full details
• Manual Retry - You can retry failed items from the deployment history

Common Scenarios

Scenario 1: Deploying a New Custom Object

What you're deploying:

• 1 custom object (with 20 properties included)

What happens:

• Sequential strategy creates the custom object
• All 20 properties are included in the creation payload
• Total time: ~3 seconds

Scenario 2: Adding Properties to Existing Object

What you're deploying:

• 50 new properties for Contacts

What happens:

• Batch strategy is used
• Properties split into 1 batch of 50
• Total time: ~3 seconds

Scenario 3: Updating Existing Properties

What you're deploying:

• 50 property updates for Contacts

What happens:

• Sequential strategy is used (updates not supported in batch)
• Each property updated individually
• Total time: ~100 seconds

Scenario 4: Mixed Deployment

What you're deploying:

• 30 new Contact properties (create)
• 10 existing Contact properties (update)
• 5 workflows (create)

What happens:

1. 30 new properties deployed via Batch (~2 seconds)
2. 10 property updates deployed via Sequential (~20 seconds)
3. 5 workflows deployed via Sequential (~10 seconds)
4. Total time: ~32 seconds

Best Practices

Group Similar Operations

When possible, group similar operations together:

• Deploy all new properties in one batch
• Deploy all updates in another batch
• This maximizes the benefit of batch deployment

Expect Different Speeds

Don't be surprised if:

• Creating 100 properties takes 5 seconds
• Updating 100 properties takes 3 minutes

This is normal - different strategies have different performance characteristics.

Monitor Deployment Logs

Watch the deployment logs to understand:

• Which strategy is being used for each item
• How long each batch or item takes
• Which items succeed or fail

Plan for Sequential Deployments

For large sequential deployments (100+ workflows, forms, etc.):

• Expect them to take several minutes
• Don't interrupt the deployment
• Review logs if any items fail

Troubleshooting

Batch Deployment Fails Completely

If an entire batch fails:

• Check HubSpot API status (might be down)
• Verify your connection has the required scopes
• Review error message in deployment logs
• Retry the deployment after resolving the issue

Sequential Deployment is Slow

If sequential deployment seems unusually slow:

• This is expected behavior for large deployments
• Each item requires a separate API call
• HubSpot rate limits may slow down requests
• The system automatically handles rate limiting

Some Items Fail in Batch

If some items fail in a batch deployment:

• Review the error message for each failed item
• Common causes: invalid property names, duplicate properties, missing required fields
• Fix the issues in the source
• Retry the deployment with only the failed items

Rate Limit Errors

If you see rate limit errors (429):

• The system automatically retries with delays
• This is normal for large deployments
• The deployment will continue, just slower
• No action needed from you

Related Features

• Dependency Resolution - How deployment order is determined
• Pre-Deployment Backups - Automatic backups before deployment
• Assisted Deployment - Manual deployment with retry options
• Deployment History - View past deployment results