Drop Docs

Integrations

The merchant portal supports two platform connectors today, Shopify and Wix. If you run your own custom software instead, use Native integration with the Orders API and optional outbound webhooks.

Shopify connector

Use this when Shopify is the source of truth for incoming orders. Save the Shopify store connection in the portal, choose the pickup store, then register Shopify webhooks with the exact Drop URL and secret.

Wix connector

Use this when Wix is the source of truth for incoming orders. Save the Wix site connection in the portal, choose the pickup store, then download the generated Wix backend files and add them to the merchant site.

Native integration

Use this only when you run your own website, app, checkout flow, POS, or backend. Native integration is separate from Shopify and Wix and gives your own system API credentials and optional Drop webhook delivery.

How the portal expects setup to happen

Add a pickup store first

Platform connectors need a pickup store because Drop must know which store should dispatch incoming orders.

Choose the right integration path

Use Shopify connector or Wix connector when those platforms are the order source. Use Native integration only when you run your own custom store, app, or backend.

Save the connector in the portal

Store identity, secret or public key, pickup store, and connector behavior are configured in the portal before you test live traffic. For Wix, Drop also generates the backend starter files immediately after save.

Verify and monitor

After setup, test the connector from Shopify or Wix and review integration events and issues in the portal.

Choose the right path

Use Shopify connector

When orders originate in Shopify and Shopify should push order changes into Drop through Shopify webhooks.

Use Wix connector

When orders originate in Wix and Wix should push paid order events into Drop through the generated backend kit.

Use Native integration

Only when you operate your own custom software and need direct Orders API access plus optional outbound Drop webhooks.

Shopify connector in the portal

Open the portal Integrations page and choose Shopify connector.

Save the connector name, Shopify store domain, Shopify webhook secret, and pickup store.

Link a Native integration app only if you separately want your own custom system credentials or Drop-to-your-system webhooks.

Shopify connector fields

text

Required for a standard Shopify connector:
- connection name
- Shopify store domain
- Shopify webhook secret
- pickup store

Optional:
- linked Native integration app
- paid-order-only filter
- auto-create orders toggle

Shopify webhook target

text

Delivery URL
POST /integrations/shopify/orders

Recommended Shopify topics
- orders/create
- orders/updated
- orders/cancelled

Required Shopify headers
- X-Shopify-Topic
- X-Shopify-Shop-Domain
- X-Shopify-Hmac-Sha256

Wix connector in the portal

Open the portal Integrations page and choose Wix connector.

Save the connector name, Wix site ID, webhook mode details, and pickup store.

Link a Native integration app only if you separately want your own custom system credentials or Drop-to-your-system webhooks.

Download the generated Wix starter kit from the portal, add dropsa.jsw and events.js in Wix Backend, publish the site, then monitor portal events and errors.

Wix connector fields

text

Required for a standard Wix connector:
- connection name
- Wix site ID
- pickup store

Choose one verification mode:
- signed Wix webhook public key
- automation verification token (Drop can generate this)

Optional:
- linked Native integration app
- paid-order-only filter
- auto-create orders toggle

Wix webhook target and generated files

text

Delivery URL
POST /integrations/wix/orders

Generated from the portal after save
- backend/dropsa.jsw
- backend/events.js
- README.md

Supported Wix flows
- signed Wix webhook payloads using the configured public key
- Wix backend event flow using webhookVerificationToken in the JSON body

Wix backend starter kit

What Drop generates

As soon as you save a Wix connector in the portal, Drop prepares three downloadable files for the merchant: dropsa.jsw, events.js, and a short setup guide. These files are ready to add directly in Wix Editor.

Where to add them in Wix

In Wix Editor, enable Dev Mode and go to Backend & Public -> Backend. Create a web module named dropsa.jsw and a backend file named events.js, then paste the generated files exactly as provided by Drop.

Important Wix webhook behavior

Paid orders are preferred

The generated Wix backend kit listens for wixStores_onOrderPaid so Drop receives the order after payment rather than on raw order creation.

Duplicate delivery can happen

Wix can resend the same webhook event. Drop uses the Wix webhook event id to ignore duplicate deliveries safely.

Events may arrive out of order

Connector logic should not assume that every later delivery arrives after every earlier one. Monitor portal events and issues instead of depending on arrival order alone.

Address geocoding fallback

Wix often omits latitude and longitude. Drop now geocodes the Wix delivery address automatically when coordinates are missing, so merchants do not need to provide them manually in Wix.

When to use Native integration instead

Native integration is the right path when your own software is the order source of truth. This includes custom websites, apps, internal order desks, POS systems, marketplace bridges, and other non-Shopify/non-Wix flows.

What Native integration gives you

A merchant app identity, client credentials for the Orders API, and optional outbound Drop webhooks to your own backend.

What it is not for

It is not required just to connect Shopify or Wix. Those should use the dedicated platform connector flow in the portal.

Native integration setup flow

Create a Native integration app in the portal Developers page. This gives your own backend a client ID and secret.

Exchange those credentials for a bearer token through the OAuth token endpoint.

POST your orders to the Orders API using JSON with pickup, dropoff, customer, package, amount, and currency.

Add an outbound webhook endpoint only if your own backend should receive signed Drop lifecycle events later.

Native integration essentials

text

Base URL
https://api.dropsa.co.za

Authentication
POST /oauth/token

Create order
POST /v1/orders

Use Native integration when your own website, mobile app, POS, or backend is the source of truth for the order.

Get an access token

bash

curl -X POST https://api.dropsa.co.za/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "drop_live_app_asteria",
    "clientSecret": "drop_live_secret_replace_me"
  }'

Create an order

bash

curl -X POST https://api.dropsa.co.za/v1/orders \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "reference": "AST-100245",
  "channel": "api",
  "sellerType": "merchant_managed",
  "fulfilmentType": "same_time_delivery",
  "serviceType": "EXPRESS",
  "pickup": {
    "addressLine1": "18 Fricker Road",
    "city": "Johannesburg",
    "country": "ZA",
    "latitude": -26.1076,
    "longitude": 28.0567,
    "contactName": "Asteria Dispatch Desk",
    "contactPhone": "+27115550190"
  },
  "dropoff": {
    "addressLine1": "77 Grant Avenue",
    "addressLine2": "Unit 4",
    "city": "Johannesburg",
    "country": "ZA",
    "latitude": -26.1453,
    "longitude": 28.0316,
    "contactName": "Lebo Khumalo",
    "contactPhone": "+27710001122"
  },
  "customer": {
    "name": "Lebo Khumalo",
    "phone": "+27710001122",
    "email": "lebo.khumalo@example.test"
  },
  "package": {
    "size": "SMALL",
    "weightKg": 1.2,
    "category": "STANDARD"
  },
  "amount": 189.5,
  "currency": "ZAR",
  "notes": "Call on arrival and hand to reception."
}'

Example native order payload

json

{
  "reference": "AST-100245",
  "channel": "api",
  "sellerType": "merchant_managed",
  "fulfilmentType": "same_time_delivery",
  "serviceType": "EXPRESS",
  "pickup": {
    "addressLine1": "18 Fricker Road",
    "city": "Johannesburg",
    "country": "ZA",
    "latitude": -26.1076,
    "longitude": 28.0567,
    "contactName": "Asteria Dispatch Desk",
    "contactPhone": "+27115550190"
  },
  "dropoff": {
    "addressLine1": "77 Grant Avenue",
    "addressLine2": "Unit 4",
    "city": "Johannesburg",
    "country": "ZA",
    "latitude": -26.1453,
    "longitude": 28.0316,
    "contactName": "Lebo Khumalo",
    "contactPhone": "+27710001122"
  },
  "customer": {
    "name": "Lebo Khumalo",
    "phone": "+27710001122",
    "email": "lebo.khumalo@example.test"
  },
  "package": {
    "size": "SMALL",
    "weightKg": 1.2,
    "category": "STANDARD"
  },
  "amount": 189.5,
  "currency": "ZAR",
  "notes": "Call on arrival and hand to reception."
}

Native payload checklist

text

Required in practice
- reference
- pickup address and contact
- dropoff address and contact
- customer details
- package details
- amount
- currency

Recommended
- latitude and longitude for both pickup and dropoff when your system already knows them
- notes for access, handoff, or delivery instructions

Good uses for Native integration
- custom ecommerce storefronts
- marketplace bridges
- POS or order desk software
- internal order management systems

Orders API example for Native integration

json

{
  "reference": "FC-100245",
  "channel": "website",
  "originSystem": "custom-storefront",
  "pickupAddressLine1": "Sandton City, Rivonia Road",
  "dropoffAddressLine1": "Centurion Mall, Heuwel Avenue",
  "dropoffContactName": "Lerato Nkosi",
  "dropoffPhone": "+27821234567"
}