Help Center

Introduction

This guide explains how to develop a custom shipping carrier integration for your CRM’s marketplace. Integrating a custom carrier allows businesses to connect their preferred shipping providers, display real-time shipping rates at checkout, automate order fulfillment, and sync tracking details directly into customer orders—enhancing the built-in e-commerce features of the CRM.

Key benefits include:

Flexibility: Connect any carrier with an API, beyond default options.
Accurate Rates: Show live shipping costs from your carrier during checkout.
Automated Fulfillment: Generate shipping labels and trigger shipments automatically.
Seamless Tracking: Sync carrier tracking updates back to CRM orders.
Integrated Experience: Manage shipping entirely within the CRM.

Building this integration requires backend development for API calls and webhooks, a frontend for user configuration (often via a Custom Page), and secure handling of credentials between the CRM, your service, and the carrier.

Requirements

Technical Knowledge

Basic backend development skills (e.g., Node.js, Python), understanding of REST APIs, webhooks, and OAuth 2.0 flows.

Backend Service

A backend service that can:

Handle OAuth redirection from the CRM.
Process webhooks from the CRM (e.g., order events) and the custom carrier (e.g., shipping updates).
Make API calls to both the CRM and the carrier’s API.
Serve the frontend UI if not hosted separately.

Database

A database to securely store:

CRM OAuth tokens (access and refresh tokens) linked to location IDs.
Carrier credentials (e.g., API keys, secrets) provided by users, associated with CRM locations.
Mappings between CRM orders and carrier entities.

Frontend

A simple frontend (e.g., a CRM Custom Page) where users can:

Start the connection process.
Enter and save their carrier API credentials.
Manage connection settings like enabling/disabling features.

APIs

Your backend must implement these endpoints:

OAuth Redirect URI: Handles the callback after app authorization.
CRM Webhook Listener: Receives webhooks for events like OrderCreate and OrderStatusUpdate.
Carrier Credential Management: APIs to save, update, or delete credentials from the frontend.
Carrier Webhook Listener: Receives webhooks from the custom carrier.
Live Rates Callback: An endpoint the CRM calls to fetch shipping rates during checkout.

Initial Setup

Create Marketplace App

Create a new Marketplace application in your CRM following its authorization documentation.

Configure App Settings

Set the application type to Sub-Account for installation on specific location accounts. Configure the Redirect URI to your backend’s OAuth callback endpoint (e.g., https://your-backend.com/oauth/callback) and the Webhook URL to your CRM webhook listener (e.g., https://your-backend.com/webhooks/crm). Enable OrderCreate and OrderStatusUpdate webhooks in the app settings.

Required Scopes

Your app needs these scopes: orders.readonly, orders.write, shipping.readonly, and shipping.write. Refer to your CRM’s scopes documentation for exact names.

Frontend UI (Custom Page)

Develop a frontend interface for users to enter carrier credentials (e.g., API Key, Secret). Embed this in the CRM using a Custom Menu Link pointing to your hosted UI or an endpoint serving it.

Handling User Context

Your frontend and backend must identify the CRM location the user is accessing. Use the context provided when the CRM loads your custom page, typically by parsing a token (like a JWT or encrypted payload) passed as a query parameter. Decrypt and validate this token with your app’s shared secret to obtain the locationId.

Live Shipping Rates Implementation

Register Shipping Carrier in CRM

Implement Live Rates Callback

Set up the endpoint the CRM calls during checkout to fetch live shipping rates from your carrier. Your service should return rate options based on the order details.

Configure Shipping Rates in CRM Zones

Configure shipping zones in the CRM to use your custom carrier for rate calculations, ensuring rates display correctly during checkout.

Order Syncing and Fulfillment

Enable Order Webhooks

Ensure your app has OrderCreate and OrderStatusUpdate webhooks enabled to receive order events from the CRM.

Handling Order Creation Webhook

When an order is created, your backend should process the webhook, create a shipment with the carrier, and update the CRM order with shipping details.

Handling Carrier Shipping Updates

Receive webhooks from the carrier for shipping updates (e.g., tracking numbers), and sync these back to the CRM order to keep customers informed.

Disconnection and Uninstallation

Deleting the Shipping Carrier

Provide a way for users to disconnect the carrier, which should remove credentials and stop syncing. Handle app uninstallation by cleaning up stored data and revoking access.

Conclusion

By following this guide, you can build a robust custom shipping carrier integration that streamlines shipping operations within your CRM, offering users flexibility, accuracy, and automation.

Custom Shipping Carrier Integration Guide