ShipStation to HubSpot contact sync (shipment notes + tracking)

Build an agent workflow that runs on a cron schedule every few hours (default: every 2 hours) and keeps HubSpot contacts up to date with their latest ShipStation shipping activity, so sales and CS reps see fulfillment context inside the CRM.

On each run, the agent should:

1. Call ShipStation List Shipments for a recent window (roughly the last few hours, slightly wider than the schedule interval so nothing falls through the cracks). Page through results if there are more than fit in one response.

2. For each shipment that has a recipient email on ship_to.email, call HubSpot Search Contacts to find a contact whose email matches that recipient email exactly.

3. If no matching contact is found, skip that shipment. Do NOT create a new HubSpot contact. Recipients on a shipment are often gift recipients or different people from the buyer, and we don't want to pollute the CRM.

4. If a matching contact is found, call HubSpot Create Note associated to that contact. The note body should be a short, human-readable shipment summary including: carrier, service level, tracking number, ship date, and current shipment status. Keep it to 3 to 5 short lines, suitable for a rep glancing at the contact timeline.

5. Also call HubSpot Update Contact on that same contact to write the most recent tracking number and ship date into two existing custom contact properties (assume they are already created in HubSpot; common names are last_tracking_number and last_shipment_date, but the agent should be configurable on the exact property internal names). Only overwrite if this shipment's ship date is newer than the current value, so older runs don't clobber newer data.

Important behavior:

- Use ShipStation V2 (api.shipstation.com/v2), not V1.

- Before creating a note, check whether a note with the same tracking number already exists on the contact and skip if so, to avoid duplicates when runs overlap.

- Respect rate limits on both sides. ShipStation has a 200/min default; HubSpot Search is 4/sec. The agent should pace its work, not fire all calls in parallel.

- At the end of each run, log a one-line summary: shipments processed, contacts updated, shipments skipped because no contact match, and any errors. This makes it easy to confirm the workflow is doing its job.

Inputs to expose for the user to configure: schedule cadence (default every 2 hours), lookback window in hours (default 3), the internal names of the two custom HubSpot contact properties to write the tracking number and ship date into, and an optional toggle for what to do with unmatched recipients (skip silently vs. log to the run summary).

Additional information

What does this prompt do?

Pulls recent ShipStation shipments on a recurring schedule (every few hours by default).
Finds the matching HubSpot contact by recipient email, and skips shipments that don't match an existing contact so you never create stray records.
Drops a short fulfillment note on the contact: carrier, service, tracking number, ship date, and current status.
Writes the latest tracking number and ship date into HubSpot contact properties so reps can filter and sort views by fulfillment activity.

What do I need to use this?

A ShipStation account with an API key you can generate from Settings.
A HubSpot login with permission to read contacts and write notes and contact properties.
Two custom contact properties already created in HubSpot for the latest tracking number and the latest ship date.

How can I customize it?

Change how often it runs. Every two hours, every six hours, or once a day depending on how fast your fulfillment moves.
Adjust the lookback window so the agent only processes shipments from the last few hours and doesn't repeat work.
Tweak the note format to include extra fields you care about, like store name, order number, or estimated delivery date.
Decide what to do with unmatched recipients. Skip them by default, or send them to a Slack channel for review.

Frequently asked questions

What happens if a shipment recipient isn't in HubSpot?

The agent skips that shipment instead of creating a new contact. Recipients are often gift recipients or different people than the buyer, so auto-creating them tends to pollute your CRM. If you want unmatched recipients surfaced, add a Slack ping or a review queue.

Will this duplicate notes on the same contact?

The agent processes a rolling window of recent shipments, so as long as the schedule and lookback window line up (for example, run every 2 hours and look back 3 hours), each shipment lands on the contact exactly once. You can also have the agent check for an existing note with the same tracking number before writing a new one.

Do I need to create the custom HubSpot properties myself?

Yes. Before turning this on, add two custom contact properties in HubSpot (commonly named something like Last tracking number and Last ship date). The agent writes into those existing properties, it doesn't create new fields.

Can I send the note to the company or deal instead of the contact?

Yes. The default associates the note with the matching contact, but you can adjust the workflow to also attach it to the contact's primary company or open deals so account owners see it on the right record.

Does this work with ShipStation V1 keys?

No. This uses the modern ShipStation V2 API. Generate a V2 key from your ShipStation Settings under API Settings. Legacy V1 keys won't work.