Aliexpress Dropship Laravel Package

Getting Started

Confirm what you actually cloned. With zero stars, zero dependents and no score, treat this repo as unvetted. Before writing any code, check composer.json for a name, type, autoload PSR-4 map, and a laravel key under extra — some Bagisto extension repos are placeholders or mirrors that only contain a README plus a license file. If the src/ tree is missing or empty, stop and look for the same extension on the Bagisto marketplace instead.

It is a Bagisto extension, not a general Laravel package. The hard prerequisite is a working Bagisto install (matching the major version declared in the package's composer.json require block — typically bagisto/bagisto). Do not try to install it into a bare Laravel app; it expects Bagisto's admin ACL, configuration repository, attribute system, and product/customer/order models to exist.

Minimal path:

composer require bagisto/aliexpress-dropship
php artisan vendor:publish --tag=config      # see what tags exist: php artisan vendor:publish (interactive)
php artisan migrate                          # adds the aliexpress_* tables
php artisan optimize:clear

If the service provider is not auto-discovered, register it manually in config/app.php / bootstrap/providers.php.

Get credentials before touching code. You need an app on the AliExpress Open Platform (the dropshipping/"aliexpress.ds" API family, not the affiliate API). That means an app_key, an app_secret, and — for seller-scoped dropship calls — an OAuth access_token for the seller account. Note which flavor of credential the admin config screen asks for; a key/secret pair alone will only get you catalogue reads.

Where to look first, in this order:

1. src/Providers/*ServiceProvider.php — shows every binding, command, route and config merge the package contributes. This is your map.
2. src/Config/ (or config/) — the admin/system config tree; tells you which settings are env-backed vs DB-backed.
3. src/Console/Commands/ — the sync/import entry points. Run php artisan list and grep for aliexpress rather than trusting README command names.
4. database/migrations/ — the mapping tables. The schema tells you the intended data flow faster than the README does.

First use case: import exactly one product by its AliExpress product ID, end to end. That single run exercises credentials, signature generation, HTTP transport, category/attribute mapping, image download, and variant creation. If it succeeds you have a working baseline; if it fails you have one error instead of a thousand.

Implementation Patterns

Wrap the package's API client, don't call it from controllers. Bind the package's client/repository behind your own interface in a small app-level service, and inject that. AliExpress API behavior changes (signature scheme, deprecations, rate limits), and you want one seam to patch or mock rather than a dozen call sites.

Everything is a queued job, nothing is a web request. Product imports, price/stock sync, and order placement all hit a rate-limited third-party API. Pattern:

// App\Jobs\FulfillAliExpressOrder
public function handle(AliExpressOrderService $service): void
{
    $service->placeOrder($this->orderId);
}

Then hook Bagisto's order-placed event via a listener and dispatch the job, so checkout latency never depends on AliExpress being up. Configure a dedicated queue worker and a rate limiter (RateLimiter::for('aliexpress', fn () => Limit::perMinute(30))) — the open platform throttles aggressively and will hand you a 200 with an error code rather than a 429.

Import flow, the pattern that survives:

1. Fetch product detail by ID.
2. Resolve or create the Bagisto category (cache a mapping table; never fuzzy-match on every import).
3. Map to an existing attribute family/attribute set — pick a dedicated aliexpress family up front rather than reusing default, otherwise your imports silently drop variant options.
4. Create one Bagisto product plus one child per AliExpress SKU, keyed by the SKU's sku_id/sku_attr string, not by display name (names repeat and get localized).
5. Download images into Bagisto's storage rather than storing AliExpress CDN URLs — those URLs expire and are referer-checked.
6. Persist the mapping row (bagisto product id ↔ aliexpress product id, variant id ↔ sku id). Every subsequent sync depends on it.

Use updateOrCreate on the mapping key for syncs. Price and inventory sync must be idempotent and re-runnable; the cron will overlap eventually. Key on the AliExpress identifier, never on the SKU string.

Price sync pattern: store your markup rule (fixed, percentage, or tiered) in config, and keep a per-product price_locked flag. The failure mode everyone hits is a manual price edit being silently overwritten at 2 a.m. Store the source AliExpress price alongside your computed price so you can explain any discrepancy.

Order fulfillment pattern: mirror the Bagisto order into a local aliexpress_orders row with status, then progress it through a state machine (pending → placed → shipped → delivered → failed) driven by a poll command. On shipped, read the tracking number from the AliExpress response and create a Bagisto shipment so the customer gets it in their account, not just via email.

Multi-store: if you run several Bagisto channels, verify whether the credential/config layer is per-channel or global. If it's global, keep separate app instances or fork the config repository — sharing an access token across sellers gets confusing fast.

Extension points to lean on: the published config file, container bindings (rebind a repository or client class to override behavior), and Laravel events. Overriding the repository via container binding is usually cleaner than editing vendor/.

Gotchas and Tips

Signature failures are the #1 support ticket. AliExpress request signing sorts parameters, concatenates them into a specific pattern, and hashes with the declared sign_method. Timestamps must be in the API's expected format/timezone (usually UTC and milliseconds, not seconds). If you get a generic "invalid signature", dump the exact string-to-sign and compare it character by character — sorting of nested/array params and empty-value handling is where it breaks.

Credential confusion. The affiliate API (tracking ID based) and the dropshipping API (OAuth access token based) are different products on the same platform. Mixing the two gives you either 401s or an empty catalogue. Check whether the admin config screen wants app_key/app_secret only or also access_token/refresh_token, and put a token-refresh job on the schedule if the latter.

Watch the response envelope. AliExpress frequently returns HTTP 200 with an error body (error_response / code/msg). Any naive Http::get()->json() code that only checks status codes will report success while importing nothing. Assert on the payload, not the status.

Category mapping is the ongoing cost, not a one-time task. AliExpress categories and Bagisto categories don't correspond. Budget for a mapping table plus an admin screen to review unmatched categories — otherwise imports land in "Root" and your storefront navigation degrades.

Attribute mapping determines sellability. A product imported without name, url_key, price, weight, visibility, and the attribute-family-required fields will exist in the DB but be unbrowsable and unbuyable. After import, spot-check one product in the admin edit form for missing required attributes rather than trusting the "imported successfully" flash.

Variants explode. A single AliExpress listing can have hundreds of SKU combinations. Chunk the variant creation, and expect image and attribute work per child to dominate import time. Add a hard cap and log oversized products for manual handling.

Inventory is unreliable. AliExpress stock counts lag and are sometimes wildly wrong. Keep a configurable buffer (e.g. treat stock < N as 0) and never let sync set your quantity above what the source claims.

Prices move between view and checkout. For dropship ordering, re-fetch the price at placement time and abort if it drifted beyond a tolerance — otherwise you eat the difference. Also validate the customer address/phone before submitting; AliExpress rejects orders for missing phone numbers and for countries it doesn't serve, and the error messages are unhelpful.

HTTP client hygiene: always set explicit ->timeout() and ->retry() with backoff, and pass a User-Agent. Default Laravel timeouts are too long for batch jobs and too short for large product payloads.

Scheduling is on you. Many extensions ship the command but not a schedule() entry. Verify with php artisan schedule:list; if the sync commands aren't there, add them to routes/console.php or bootstrap/app.php yourself, and make sure the system cron actually runs schedule:run. Without that, everything "works" in your manual test and nothing updates in production.

Debugging workflow: reproduce through the artisan command, not the admin UI — you get cleaner stack traces. Enable a dedicated log channel, log the raw request/response bodies (redact the secret) into a table so you can replay a failed import rather than re-hitting the API. Http::preventStrayRequests() plus a mock in tests will keep CI from calling AliExpress.

Vendor it if you need to patch. With zero dependents there is no community pressure to fix bugs upstream. If you find yourself editing vendor/, switch to a VCS path repository so your fixes are tracked and reviewable, and be prepared to reapply them on every composer update.

Upgrade friction: these packages tend to have loose or missing version constraints against bagisto/bagisto core and to publish migrations you cannot easily change later. Pin versions, and take a database dump before every package upgrade.