Building a Dropshipping Integration for Your CRM Marketplace App

Introduction

This guide outlines the process for creating and publishing a dropshipping integration as a marketplace application for your CRM. You will learn how to build provider integrations that handle logistics, fulfillment, and shipping, connecting external services to the CRM platform and distributing them through the marketplace.

Marketplace App Creation

Begin by creating your app in the Marketplace. Select the distribution type—either Agency or Sub-Account—and complete the app profile. Add the necessary OAuth scopes based on the APIs you intend to use, such as products, prices, orders, fulfillments, or webhooks. Generate your client credentials, including a Client ID and Secret, to establish your app's identity and permissions.

Authorization Handling

Configure the OAuth Redirect URL in your app settings. Implement a GET callback endpoint to receive the authorization code, then exchange it for access and refresh tokens. Store these tokens securely. Set up a POST webhook endpoint and add its URL to your app settings. Finally, assign locations or accounts to your app and verify the connection.

Product Sync

Use the Public API to sync products from your provider to the CRM. First, create a product with core fields like name, location ID, description, product type (physical or digital), availability in store, image, and media. For products with variants, include variant options such as color or size, and note their IDs. Then, create one or more prices for the product, referencing its ID. Include the location ID, price type (one-time or recurring), currency, amount, SKU, and optional inventory flags. For variant products, pass the variant option IDs that match specific combinations. For physical products, include shipping options with weight and dimensions.

Order Webhooks

Subscribe to OrderCreate and OrderStatusUpdate webhooks to handle order export and updates. The OrderCreate webhook contains order details, customer information, shipping and billing addresses, line items with price and SKU, currency, amounts, and optional metadata. Use this to create or update the corresponding order in your provider system, mapping each line item to the provider's SKU or variant. The OrderStatusUpdate webhook includes order ID, status transitions, timestamps, and fulfillment-related signals. Use it to trigger order creation in your provider only when the status is eligible, or to cancel or hold orders as needed.

Fulfillment Webhooks

Subscribe to your provider's shipment or fulfillment webhooks. When a shipment is created or updated, build a fulfillment payload for the corresponding CRM order and submit it. Map the provider's shipment details to the CRM fulfillment, including the internal order ID, items with price or variant identifiers and fulfilled quantities, and tracking information such as tracking number, shipping carrier, and tracking URL. Optionally, notify the customer. Use the API to create the fulfillment.

Custom Pages

If desired, extend your Marketplace app with custom pages to provide richer user interfaces and flows. These pages allow you to embed provider-specific setup, advanced settings, or dashboards within the CRM while preserving user context. Common uses include connection wizards, verification steps, shipping preferences, carrier service mappings, and troubleshooting pages. Ensure you pass and validate user context to securely identify the installing user or location when rendering your page.

Conclusion

You now have a comprehensive blueprint for building a dropshipping integration from end to end. Create and scope your Marketplace app, complete OAuth and token storage, sync catalog data using the Products and Prices APIs, subscribe to order webhooks for export, consume provider shipment webhooks to create fulfillments, and optionally enhance the user experience with custom pages. Refer to linked documentation for detailed examples and payloads as you implement each step.