Build a Dropshipping Integration for Sparkforge Stores

This guide walks through publishing a dropshipping integration to the Sparkforge Marketplace. The same structure applies to any logistics, fulfillment, or shipping provider you want to connect.

1. Create the Marketplace app

Register the app in the Marketplace, set distribution to Agency or Sub-Account, complete the profile, attach OAuth scopes for the APIs you plan to call, and generate Client ID and Secret. The scope list should cover products, prices, orders, fulfillments, and webhooks at minimum.

2. Handle authorization

Configure the OAuth Redirect URL in app settings, then implement:

• A GET callback endpoint to receive the authorization code.
• Token exchange for access and refresh tokens, stored securely.
• A POST webhook endpoint registered in app settings.

Assign locations or accounts to the app and verify the connection before publishing.

3. Sync products and prices

Use the Public API to create the Product first, then one or more Prices.

Product creation

Required fields: name, locationId, description, productType (PHYSICAL or DIGITAL), availableInStore, image, medias. For variant products, include variants with options like Color and Size and keep the option IDs for the price step.

Price creation

Reference the product _id and include locationId, type (one_time or recurring), currency, amount, sku, and any inventory flags. For variant prices, pass variantOptionIds matching the combination. Physical products need shippingOptions with weight and dimensions.

After prices exist, you can map images to specific variants by updating Product medias with priceIds.

4. Subscribe to order webhooks

Two webhooks drive order export to your provider:

OrderCreate

Includes order header, customer info, shipping and billing addresses, line items with price and SKU, totals, and metadata. Map each line item to your provider's SKU or variant before submitting.

OrderStatusUpdate

Includes status transitions (pending, completed, cancelled), timestamps, and fulfillment signals. Use it to gate provider order creation (for example, only create when status is Completed) and to handle cancels or holds.

5. Post fulfillments back

Subscribe to your provider's shipment webhooks. When a shipment fires, build a Sparkforge fulfillment payload and POST it.

{
  "items": [{ "priceId": "66b6021be68f7a98102ba272", "qty": 2 }],
  "trackings": [
    {
      "trackingNumber": "1Z999AA10123456784",
      "shippingCarrier": "UPS",
      "trackingUrl": "https://wwwapps.ups.com/WebTracking/track?trackNums=1Z999AA10123456784"
    }
  ],
  "notifyCustomer": true
}

6. Optional custom pages

For richer setup, settings, or troubleshooting flows, add Custom Pages to your Marketplace app. They embed inside Sparkforge while preserving user context. Validate that context per the docs to identify the installing user and location.

End-to-end checklist

1. Register and scope the Marketplace app.
2. Implement OAuth and token storage.
3. Sync catalog with Products and Prices APIs.
4. Subscribe to OrderCreate and OrderStatusUpdate.
5. Post fulfillments from provider shipment events.
6. Add custom pages if needed for UX.