Introduction
This document will help you create a dropshipping integration and publish it to the marketplace app. It outlines the high-level goals and structure you’ll follow when building provider integrations (e.g., logistics, fulfillment, shipping) that connect to the platform and are distributed via the marketplace.
Dropshipping Integration
1. Marketplace App Creation
Create your app in the Marketplace: set the distribution type (Agency or Sub-Account), complete the app profile, add the required OAuth scopes, and generate client credentials (Client ID/Secret). This establishes the app’s identity and permissions.
For a detailed guide, visit the helper doc link: How to get started with the Developer's Marketplace.
Based on the APIs you plan to use (products, prices, orders, fulfillments, webhooks, etc.), ensure you add the corresponding OAuth scopes to your app. Refer to the complete scopes list here: Scopes.
2. Authorization Handling for Marketplace App
Configure the OAuth Redirect URL in app settings, then implement a GET callback endpoint to receive the authorization code. Exchange the code for access/refresh tokens, store them securely, and set up a POST webhook endpoint; add its URL in app settings. Finally, assign locations/accounts to the app and verify the connection.
For a detailed guide, visit the helper doc link: How to get started with the Developer's Marketplace.
3. Product Sync (Platform → SourCherry)
Use the Public API to first create a Product, then create one or more Prices for that product. For simple items, you will have a single price; for variant items, create a price per variant combination.
Product creation (high-level):
Create Product with core fields: name, locationId, description, productType (PHYSICAL/DIGITAL), availableInStore, image, and medias.
For variant products, include variants with variant options (e.g., Color, Size). Keep the option IDs; they are required when creating variant prices.
Price creation:
Create Price referencing the product _id: include locationId, type (one_time/recurring), currency, amount, sku, and optional inventory flags.
For variant products, pass variantOptionIds that match the specific combination (e.g., [Color: Red, Size: Small]).
For physical products, include shippingOptions with weight (value, unit) and dimensions (length, width, height, unit).
Optional: After prices are created, you can map images to specific variants by updating the Product medias with priceIds so storefronts render the correct variant image.
For a detailed guide (examples and payloads), visit: Create a Product with Price using Public API.
For the list of APIs and standard response fields, refer to: Integrations API — Standard Response Fields.
4. Order Webhooks (SourCherry → Provider)
Subscribe to two webhooks: OrderCreate and OrderStatusUpdate. These drive order export to your provider and subsequent updates.
OrderCreate webhook (schema highlights):
Contains order header (ids, dates), customer info, shipping/billing addresses, line items with price/sku, currency/amounts, and optional metadata.
Use it to create or upsert the corresponding order in your provider. Map each line item to the provider’s SKU/variant before submission.
Schema: OrderCreate
OrderStatusUpdate webhook (schema highlights):
Includes order id/status transitions (e.g., pending → completed/cancelled), timestamps, and may include fulfillment-related signals from the platform.
Use it to trigger provider order creation only when status is eligible (e.g., Completed), or to cancel/hold as needed.
Schema: OrderStatusUpdate
Using these webhooks, construct the provider-specific order payload (map items to provider SKU/variant, addresses, totals) and create/update the order in the respective platform.
5. Fulfillment Webhooks (Provider → SourCherry)
Subscribe to your provider’s shipment/fulfillment webhooks. When a shipment is created or updated, build a fulfillment payload for the corresponding SourCherry order and submit it.
Map provider shipment → SourCherry fulfillment:
Order: internal order id in SourCherry
Items: price/variant identifiers and fulfilled quantities
Tracking: trackingNumber, shippingCarrier, trackingUrl
Optionally notify the customer
Use the API to create the fulfillment: Create Order Fulfillment.
Example request body:
{
"items": [{ "priceId": "66b6021be68f7a98102ba272", "qty": 2 }],
"trackings": [
{
"trackingNumber": "1Z999AA10123456784",
"shippingCarrier": "UPS",
"trackingUrl": "https://wwwapps.ups.com/WebTracking/track?trackNums=1Z999AA10123456784"
}
],
"notifyCustomer": true
}
6. Custom Pages (Optional)
If you want to extend your Marketplace app with richer UI/flows, leverage Custom Pages. These allow embedding provider-specific setup, advanced settings, or dashboards inside SourCherry while preserving user context.
Typical uses: connection wizards, verification steps, shipping preferences, carrier service mappings, troubleshooting pages.
Authentication/User context: pass and validate user context per the guide to securely identify the installing user/location when rendering your page.
Refer to: User context in Marketplace apps.
Conclusion
You now have a compact blueprint to ship a dropshipping integration end‑to‑end:
Create and scope your Marketplace app, then complete OAuth and token storage.
Sync catalog data using Products/Prices APIs.
Subscribe to order webhooks to export orders to your provider.
Consume provider shipment webhooks and create fulfillments back in SourCherry.
Optionally enhance UX with custom pages powered by user context.
Use the linked docs for deep dives and payload examples as you implement each step.