Sync Listings using SyncListingsService

The SyncListingsService workflow provides a robust, resumable, rate-limited synchronization for eBay seller listings using the Trading API call GetSellerList. It is designed for large data sets, supports automatic pagination, time-window chunking, and queue-based execution, and exposes well-defined lifecycle hooks via a single handler class.

NOTE

This service is intended to be used in background jobs and scheduled tasks, not as a synchronous request.

Overview

• \Rat\eBaySDK\Services\SyncListingsService
  Orchestrates the sync process, calculates time windows, manages checkpoints and rate limiting
• \Rat\eBaySDK\Jobs\SyncListingsJob
  Executes one sync step, gets re-dispatched until finished
• \Rat\eBaySDK\Abstracts\SyncListingsHandler
  User-provided abstract extension point, receives data and lifecycle callbacks

Requirements

This sync must run in a queue. The service is intentionally designed to process large datasets over multiple jobs and must not be run synchronously.

At least one queue worker must be running (using the following local example):

php artisan queue:work --queue=ebay-sync

For more information visit Laravel's Queue documentation page.

Usage

Dispatching a Sync

use Rat\eBaySDK\Services\SyncListingsService;
use App\Handlers\MySyncListingsHandler;

SyncListingsService::make()
    ->from('2020-01-01')
    ->to(now())
    ->limit(200)
    ->interval('+119 days 23 hours 59 minutes 59 seconds')
    ->handler(MySyncListingsHandler::class)
    ->dispatch();

Writing a Handler

use Rat\eBaySDK\Abstracts\SyncListingsHandler;

class MySyncListingsHandler extends SyncListingsHandler
{
    /**
     *
     * @param array $item
     * @return void
     */
    public function onChunk(array $chunk): void
    {
        // Handle the whole items chunk
    }

    /**
     *
     * @param array $item
     * @return void
     */
    public function onItem(array $item): void
    {
        // Handle each single listing item
    }
}

Scheduling

The following example syncs listings weekly at 02:00 AM.

use Illuminate\Console\Scheduling\Schedule;
use Rat\eBaySDK\Abstracts\SyncListingsHandler;

$schedule->call(function () {
    SyncListingsService::make()
        ->from('2018-01-01')
        ->to(now())
        ->handler(MySyncListingsHandler::class)
        ->dispatch('ebay-sync');
})
->weeklyAt('02:00')
->withoutOverlapping();

Configuration

from(string|DateTimeInterface $date)

Sets the start date of the sync range.

->from('2018-01-01')

to(string|DateTimeInterface $date)

Sets the end date of the sync range.

->to(now())

limit(int $limit)

Number of listings / items per page. Supports values between 1 and 200 (as per eBay limitations).

->limit(200)

interval(string $interval)

Time window size for each sync chunk. Must be compatible with DateTimeImmutable::modify() (See Supported Date and time formats on php.net). Supports a maximum interval of 120 days (as per eBay limitations).

->interval('+119 days 23 hours 59 minutes 59 seconds')

handler(class-string<SyncListingsHandler> $handler)

Registers the handler class responsible for processing data. This is required for queue execution.

->handler(MySyncListingsHandler::class)

dispatch(?string $queue = null)

Dispatches the initial sync job.

->dispatch('ebay-sync');

SyncListingsHandler

The handler defines how the retrieved data is processed. It receives callbacks at different stages of the sync lifecycle.

use Rat\eBaySDK\Contracts\SyncListingsHandler;
use Rat\eBaySDK\Context\SyncListingsContext;
use Rat\eBaySDK\Response;

class MySyncListingsHandler extends SyncListingsHandler
{
    public function onPrepare(SyncListingsContext $context): void
    {
        // Prepare (called once before entire sync process)
    }

    public function onFinish(SyncListingsContext $context): void
        // Finish, Clean up (called once after entire sync process)
    }

    public function onBefore(array $payload, SyncListingsContext $context): array
    {
        // Modify request (e.g. output selectors, detail level)
        return $payload;
    }

    public function onAfter(GetSellerList $request, Response $response, SyncListingsContext $context): void
    {
        // Logging, metrics, diagnostics
    }

    public function onChunk(array $chunk, SyncListingsContext $context): void
    {
        // Bulk processing (recommended for database writes)
    }

    public function onItem(array $item, SyncListingsContext $context): void
    {
        // Per-item processing (optional)
    }
}

onPrepare(SyncListingsContext $context)

Called once before the first API request of the entire sync process.

onFinish(SyncListingsContext $context)

Called once after the sync process has fully completed.

onBefore(array $payload, SyncListingsContext $context)

Called before the API request is executed, must return the desired GetSellerList request instance.

onAfter(GetSellerList $request, Response $response, SyncListingsContext $context)

Called after the API request returns.

onChunk(array $chunk, SyncListingsContext $context)

Called once per page with all items of that page.

onItem(array $item, SyncListingsContext $context)

Called for each individual listing.