PHPackages                             tigusigalpa/ebay-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. tigusigalpa/ebay-php

ActiveLibrary[Authentication & Authorization](/categories/authentication)

tigusigalpa/ebay-php
====================

Modern PHP/Laravel package for eBay API integration with OAuth 2.0 support

v1.3.0(1mo ago)105MITPHPPHP ^8.1

Since Feb 4Pushed 1mo agoCompare

[ Source](https://github.com/tigusigalpa/ebay-php)[ Packagist](https://packagist.org/packages/tigusigalpa/ebay-php)[ RSS](/packages/tigusigalpa-ebay-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (14)Versions (5)Used By (0)

eBay PHP/Laravel SDK
====================

[](#ebay-phplaravel-sdk)

[![eBay PHP SDK](https://private-user-images.githubusercontent.com/2721390/545163206-629586b3-1a78-4919-98e0-f8fd3cef57e0.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU0Mzc2NjcsIm5iZiI6MTc3NTQzNzM2NywicGF0aCI6Ii8yNzIxMzkwLzU0NTE2MzIwNi02Mjk1ODZiMy0xYTc4LTQ5MTktOThlMC1mOGZkM2NlZjU3ZTAuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDZUMDEwMjQ3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9Mjg3M2Q5Mjg5N2RiNTdjOWI3NGE2MGM4YmNkMzhlOWRmYzk0Yjg2OGI0ODBiZTJkMzkyNjc3Y2EyZmFkZTA4NiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.WwyeyvmHZXNoy9VHcdGn8Iw33UVM2IjE1uVnPECw_IA)](https://private-user-images.githubusercontent.com/2721390/545163206-629586b3-1a78-4919-98e0-f8fd3cef57e0.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU0Mzc2NjcsIm5iZiI6MTc3NTQzNzM2NywicGF0aCI6Ii8yNzIxMzkwLzU0NTE2MzIwNi02Mjk1ODZiMy0xYTc4LTQ5MTktOThlMC1mOGZkM2NlZjU3ZTAuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDZUMDEwMjQ3WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9Mjg3M2Q5Mjg5N2RiNTdjOWI3NGE2MGM4YmNkMzhlOWRmYzk0Yjg2OGI0ODBiZTJkMzkyNjc3Y2EyZmFkZTA4NiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.WwyeyvmHZXNoy9VHcdGn8Iw33UVM2IjE1uVnPECw_IA)

[![Latest Version](https://camo.githubusercontent.com/7eb3bcabfa06af88fba5318a73418ce21ae0e3c4670b5b7b9f0ac8cbc6723020/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696775736967616c70612f656261792d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/ebay-php)[![License](https://camo.githubusercontent.com/081376cffa91ce5a7ef771d984ceabc092210948061ef309aeda0bebda0772fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74696775736967616c70612f656261792d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/ebay-php)[![PHP Version](https://camo.githubusercontent.com/a7425f36d68356cf8b98af7934f3557e3939c8853ee4bfd7b8675d917c167b10/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f74696775736967616c70612f656261792d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/ebay-php)[![Laravel](https://camo.githubusercontent.com/7c5643ad02b855581cd2dc1feb00b09e1816fa3c41666e7cb91fbf059e2e2c10/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d392532422d4646324432302e7376673f7374796c653d666c61742d737175617265266c6f676f3d4c61726176656c)](https://laravel.com)[![eBay](https://camo.githubusercontent.com/f22e87da1537601059a4775b28417aabcf6a79acd307f849e2b175fbdda4088a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f654261792d4150492d3030363444322e7376673f7374796c653d666c61742d737175617265266c6f676f3d65426179)](https://developer.ebay.com)

PHP SDK for eBay API. Supports Trading API (XML), Commerce API (REST), Fulfillment API, Logistics API, OAuth 2.0 authentication, 20+ marketplaces. Works as standalone and with Laravel.

> 📖 **[Full documentation available on Wiki](https://github.com/tigusigalpa/ebay-php/wiki)**

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Authentication](#authentication)
- [Trading API](#trading-api)
- [Commerce API](#commerce-api)
- [Fulfillment API](#fulfillment-api)
- [Logistics API](#logistics-api)
- [Message API](#message-api)
- [Working with Marketplaces](#working-with-marketplaces)
- [Enums and DTOs](#enums-and-dtos)
- [Error Handling](#error-handling)
- [Optimization](#optimization)
- [Testing](#testing)
- [FAQ](#faq)
- [Support](#support)
- [License](#license)

Features
--------

[](#features)

**API:**

- Trading API (XML) — orders, listings, categories, GetMyEbaySelling, etc.
- Commerce API (REST) — inventory, taxonomy, translation
- Fulfillment API (REST) — orders, shipping fulfillments, refunds, payment disputes
- Logistics API (REST) — shipping quotes, label generation, shipment tracking
- Message API (REST) — buyer-seller messaging, conversations, notifications
- OAuth 2.0 with automatic token refresh
- 20+ marketplaces (US, UK, DE, FR, AU, etc.)

**Code:**

- PHP 8.1+ with native Enums
- Strict typing
- Immutable DTOs
- Fluent interface
- PSR-4, PSR-7, PSR-12

**Laravel:**

- Service Provider + Facade
- Dependency Injection
- .env configuration

Requirements
------------

[](#requirements)

- PHP 8.1+
- Guzzle 7.x
- Laravel 9.x / 10.x / 11.x / 12.x (optional)
- Composer

Installation
------------

[](#installation)

```
composer require tigusigalpa/ebay-php
```

For Laravel — publish config:

```
php artisan vendor:publish --tag=ebay-config
```

Add credentials to `.env`:

```
EBAY_ENVIRONMENT=sandbox

# Sandbox
EBAY_SANDBOX_APP_ID=your-sandbox-app-id
EBAY_SANDBOX_CERT_ID=your-sandbox-cert-id
EBAY_SANDBOX_DEV_ID=your-sandbox-dev-id
EBAY_SANDBOX_RUNAME=your-sandbox-runame

# Production
EBAY_PRODUCTION_APP_ID=your-production-app-id
EBAY_PRODUCTION_CERT_ID=your-production-cert-id
EBAY_PRODUCTION_DEV_ID=your-production-dev-id
EBAY_PRODUCTION_RUNAME=your-production-runame

EBAY_DEFAULT_SITE=US
```

Get credentials at [eBay Developers Program](https://developer.ebay.com/).

Quick Start
-----------

[](#quick-start)

### Laravel (Facade)

[](#laravel-facade)

```
use Tigusigalpa\Ebay\Facades\Ebay;
use Tigusigalpa\Ebay\Enums\Site;

// OAuth URL
$url = Ebay::getConsentUrl();

// Exchange code for tokens
$tokens = Ebay::exchangeCodeForToken($code);

// Get orders
$orders = Ebay::trading()->getOrders([
    'CreateTimeFrom' => now()->subDays(30)->toIso8601String(),
]);

// Switch marketplace
Ebay::setSite(Site::UK)->trading()->getOrders();
```

### Standalone PHP

[](#standalone-php)

```
require_once 'vendor/autoload.php';

use Tigusigalpa\Ebay\Ebay;
use Tigusigalpa\Ebay\Enums\Site;

$ebay = new Ebay([
    'environment' => 'sandbox',
    'sandbox' => [
        'app_id' => 'your-app-id',
        'cert_id' => 'your-cert-id',
        'dev_id' => 'your-dev-id',
        'runame' => 'your-runame',
    ],
    'site' => Site::US,
]);

$orders = $ebay->trading()->getOrders();
```

Authentication
--------------

[](#authentication)

### OAuth 2.0 Flow

[](#oauth-20-flow)

**1. Get authorization URL:**

```
$consentUrl = Ebay::getConsentUrl(
    scopes: config('ebay.scopes'),
    state: 'your-state-parameter',
    locale: 'en-US'
);

return redirect($consentUrl);
```

**2. Handle callback:**

```
public function callback(Request $request)
{
    $code = $request->get('code');
    $tokenData = Ebay::exchangeCodeForToken($code);

    // Store tokens
    auth()->user()->update([
        'ebay_access_token' => $tokenData['access_token'],
        'ebay_access_token_expires_at' => $tokenData['expires_at'],
        'ebay_refresh_token' => $tokenData['refresh_token'],
        'ebay_refresh_token_expires_at' => $tokenData['refresh_token_expires_at'],
    ]);

    return redirect()->route('dashboard');
}
```

**3. Use tokens:**

```
$user = auth()->user();

Ebay::setAccessToken($user->ebay_access_token, $user->ebay_access_token_expires_at);
Ebay::setRefreshToken($user->ebay_refresh_token, $user->ebay_refresh_token_expires_at);

// Tokens refresh automatically when expired
$orders = Ebay::trading()->getOrders();
```

Trading API
-----------

[](#trading-api)

### Orders

[](#orders)

```
$xml = Ebay::trading()->getOrders([
    'CreateTimeFrom' => '2024-01-01T00:00:00.000Z',
    'CreateTimeTo' => '2024-12-31T23:59:59.999Z',
    'OrderStatus' => 'Active',
]);

foreach ($xml->OrderArray->Order as $order) {
    $orderId = (string) $order->OrderID;
    $total = (float) $order->Total;
}
```

### Items

[](#items)

```
// Get item
$item = Ebay::trading()->getItem('123456789');
$title = (string) $item->Item->Title;
$price = (float) $item->Item->SellingStatus->CurrentPrice;

// Create listing
$response = Ebay::trading()->addFixedPriceItem([
    'Title' => 'My Product Title',
    'Description' => 'Product description',
    'PrimaryCategory' => ['CategoryID' => '12345'],
    'StartPrice' => 99.99,
    'Quantity' => 10,
    'Currency' => 'USD',
    'Country' => 'US',
    'Location' => 'New York',
    'DispatchTimeMax' => 3,
    'ShippingDetails' => [
        'ShippingType' => 'Flat',
        'ShippingServiceOptions' => [
            'ShippingService' => 'USPSPriority',
            'ShippingServiceCost' => 5.00,
        ],
    ],
]);

$itemId = (string) $response->ItemID;
```

### Categories

[](#categories)

```
$categories = Ebay::trading()->getCategories([
    'CategorySiteID' => 0,
    'LevelLimit' => 2,
]);
```

Commerce API
------------

[](#commerce-api)

### Inventory

[](#inventory)

```
// Get
$item = Ebay::commerce()->getInventoryItem('SKU-123');

// Update quantity
Ebay::commerce()->createOrReplaceInventoryItem($sku, [
    'availability' => ['shipToLocationAvailability' => ['quantity' => $newQuantity]],
]);
```

### Fulfillment

[](#fulfillment)

```
$orders = Ebay::commerce()->getFulfillmentOrders([
    'filter' => 'orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}',
    'limit' => 50,
]);
```

### Translation

[](#translation)

```
$translated = Ebay::commerce()->translate(
    text: 'Brand New iPhone',
    fromLanguage: 'en',
    toLanguage: 'de',
    context: 'ITEM_TITLE'
);
```

### Category Aspects

[](#category-aspects)

```
$aspects = Ebay::commerce()->getItemAspectsForCategory('0', '12345');

foreach ($aspects['aspects'] as $aspect) {
    echo $aspect['localizedAspectName'];
}
```

Fulfillment API
---------------

[](#fulfillment-api)

The Fulfillment API v1 provides comprehensive order management, shipping fulfillment, refunds, and payment dispute handling.

### Get Orders

[](#get-orders)

```
use Tigusigalpa\Ebay\Http\Resources\Fulfillment\{Order, OrderSearchPagedCollection};

// Get single order
$order = Ebay::fulfillment()->getOrder('12-34567-89012');
echo $order->orderId;
echo $order->orderFulfillmentStatus;
echo $order->pricingSummary?->total?->value;

// Get multiple orders with filters
$orders = Ebay::fulfillment()->getOrders([
    'filter' => 'creationdate:[2024-01-01T00:00:00.000Z..]',
    'limit' => 50,
    'offset' => 0,
]);

foreach ($orders->orders as $order) {
    echo $order->orderId;
    echo $order->buyer?->username;
}

// Filter by order status
$orders = Ebay::fulfillment()->getOrders([
    'filter' => 'orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}',
]);

// Get specific orders by IDs
$orders = Ebay::fulfillment()->getOrders([
    'orderIds' => '12-34567-89012,12-34567-89013',
]);

// Include tax breakdown
$order = Ebay::fulfillment()->getOrder('12-34567-89012', [
    'fieldGroups' => 'TAX_BREAKDOWN',
]);
```

### Issue Refunds

[](#issue-refunds)

```
use Tigusigalpa\Ebay\Enums\ReasonForRefundEnum;

// Full refund
$refund = Ebay::fulfillment()->issueRefund('12-34567-89012', [
    'reasonForRefund' => ReasonForRefundEnum::BUYER_CANCEL->value,
    'comment' => 'Customer requested cancellation',
    'orderLevelRefundAmount' => [
        'value' => '99.99',
        'currency' => 'USD',
    ],
]);

// Partial refund for specific line items
$refund = Ebay::fulfillment()->issueRefund('12-34567-89012', [
    'reasonForRefund' => ReasonForRefundEnum::DEFECTIVE_ITEM->value,
    'refundItems' => [
        [
            'lineItemId' => '123456789',
            'refundAmount' => [
                'value' => '25.00',
                'currency' => 'USD',
            ],
        ],
    ],
]);

echo $refund->refundId;
echo $refund->refundStatus;
```

### Shipping Fulfillments

[](#shipping-fulfillments)

```
// Create shipping fulfillment
$fulfillmentId = Ebay::fulfillment()->createShippingFulfillment('12-34567-89012', [
    'lineItems' => [
        [
            'lineItemId' => '123456789',
            'quantity' => 1,
        ],
    ],
    'shippedDate' => now()->toIso8601String(),
    'shippingCarrierCode' => 'USPS',
    'trackingNumber' => '1234567890123456',
]);

// Get single fulfillment
$fulfillment = Ebay::fulfillment()->getShippingFulfillment(
    '12-34567-89012',
    $fulfillmentId
);

echo $fulfillment->shipmentTrackingNumber;
echo $fulfillment->shippingCarrierCode;

// Get all fulfillments for order
$fulfillments = Ebay::fulfillment()->getShippingFulfillments('12-34567-89012');

foreach ($fulfillments->fulfillments as $fulfillment) {
    echo $fulfillment->trackingNumber;
}
```

### Payment Disputes

[](#payment-disputes)

```
use Tigusigalpa\Ebay\Enums\{DisputeStatusEnum, EvidenceTypeEnum};

// Get dispute summaries
$disputes = Ebay::fulfillment()->getPaymentDisputeSummaries([
    'payment_dispute_status' => DisputeStatusEnum::OPEN->value,
    'limit' => 50,
]);

foreach ($disputes->paymentDisputeSummaries as $summary) {
    echo $summary->paymentDisputeId;
    echo $summary->reason;
    echo $summary->amount?->value;
}

// Get full dispute details
$dispute = Ebay::fulfillment()->getPaymentDispute('5001234567890');

echo $dispute->paymentDisputeStatus?->value;
echo $dispute->respondByDate;
echo $dispute->revision; // Required for contesting

// Get dispute activity history
$history = Ebay::fulfillment()->getActivities('5001234567890');

foreach ($history->activities as $activity) {
    echo $activity->activityType;
    echo $activity->activityDate;
}

// Upload evidence file
$uploadResponse = Ebay::fulfillment()->uploadEvidenceFile(
    '5001234567890',
    file_get_contents('/path/to/tracking-proof.pdf')
);

$fileId = $uploadResponse->fileId;

// Add evidence
$evidenceResponse = Ebay::fulfillment()->addEvidence('5001234567890', [
    'evidenceType' => EvidenceTypeEnum::PROOF_OF_DELIVERY->value,
    'files' => [
        ['fileId' => $fileId],
    ],
    'lineItems' => [
        [
            'itemId' => '123456789',
            'lineItemId' => '987654321',
        ],
    ],
]);

$evidenceId = $evidenceResponse->evidenceId;

// Update evidence
Ebay::fulfillment()->updateEvidence('5001234567890', [
    'evidenceId' => $evidenceId,
    'evidenceType' => EvidenceTypeEnum::PROOF_OF_DELIVERY->value,
    'files' => [
        ['fileId' => $fileId],
    ],
]);

// Contest dispute
Ebay::fulfillment()->contestPaymentDispute('5001234567890', [
    'revision' => $dispute->revision,
    'returnAddress' => [
        'addressLine1' => '123 Main St',
        'city' => 'New York',
        'stateOrProvince' => 'NY',
        'postalCode' => '10001',
        'countryCode' => 'US',
        'fullName' => 'Your Company',
    ],
]);

// Accept dispute
Ebay::fulfillment()->acceptPaymentDispute('5001234567890');

// Download evidence file
$fileContent = Ebay::fulfillment()->fetchEvidenceContent(
    '5001234567890',
    $evidenceId,
    $fileId
);

file_put_contents('evidence.pdf', $fileContent);
```

### Filter Examples

[](#filter-examples)

```
// Orders created in date range
$orders = Ebay::fulfillment()->getOrders([
    'filter' => 'creationdate:[2024-01-01T00:00:00.000Z..2024-12-31T23:59:59.999Z]',
]);

// Orders by fulfillment status
$orders = Ebay::fulfillment()->getOrders([
    'filter' => 'orderfulfillmentstatus:{NOT_STARTED}',
]);

// Disputes by buyer
$disputes = Ebay::fulfillment()->getPaymentDisputeSummaries([
    'buyer_username' => 'buyer123',
]);

// Disputes by order ID
$disputes = Ebay::fulfillment()->getPaymentDisputeSummaries([
    'order_id' => '12-34567-89012',
]);

// Disputes opened in date range
$disputes = Ebay::fulfillment()->getPaymentDisputeSummaries([
    'open_date_from' => '2024-01-01T00:00:00.000Z',
    'open_date_to' => '2024-12-31T23:59:59.999Z',
]);
```

### OAuth Scopes

[](#oauth-scopes)

Fulfillment API requires specific OAuth scopes:

- **Read operations**: `https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly`
- **Write operations**: `https://api.ebay.com/oauth/api_scope/sell.fulfillment`
- **Refunds**: `https://api.ebay.com/oauth/api_scope/sell.finances`
- **Payment disputes**: `https://api.ebay.com/oauth/api_scope/sell.payment.dispute`

Add to `config/ebay.php`:

```
'scopes' => [
    'https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly',
    'https://api.ebay.com/oauth/api_scope/sell.fulfillment',
    'https://api.ebay.com/oauth/api_scope/sell.finances',
    'https://api.ebay.com/oauth/api_scope/sell.payment.dispute',
],
```

Logistics API
-------------

[](#logistics-api)

The Logistics API v1\_beta provides shipping quote generation, label creation, and shipment management through eBay's integrated shipping carriers.

### Create Shipping Quote

[](#create-shipping-quote)

```
use Tigusigalpa\Ebay\Http\Resources\Logistics\{ShippingQuote, Shipment};

// Create a shipping quote to get available rates
$quote = Ebay::logistics()->createShippingQuote([
    'orderId' => '12-12345-12345',
    'packageSpecification' => [
        'dimensions' => [
            'length' => '10',
            'width' => '10',
            'height' => '5',
            'unit' => 'INCH',
        ],
        'weight' => [
            'value' => '2',
            'unit' => 'POUND',
        ],
    ],
    'shipFrom' => [
        'fullName' => 'John Seller',
        'contactAddress' => [
            'addressLine1' => '123 Main St',
            'city' => 'San Jose',
            'stateOrProvince' => 'CA',
            'postalCode' => '95131',
            'countryCode' => 'US',
        ],
        'primaryPhone' => [
            'phoneNumber' => '555-1234',
        ],
        'email' => 'seller@example.com',
    ],
    'shipTo' => [
        'fullName' => 'Jane Buyer',
        'contactAddress' => [
            'addressLine1' => '456 Oak Ave',
            'city' => 'Austin',
            'stateOrProvince' => 'TX',
            'postalCode' => '78701',
            'countryCode' => 'US',
        ],
    ],
]);

echo $quote->shippingQuoteId;
echo $quote->expirationDate;

// Review available rates
foreach ($quote->rates ?? [] as $rate) {
    echo $rate->shippingServiceName;
    echo $rate->shippingCost?->value;
    echo $rate->shippingCost?->currency;
    echo $rate->minEstimatedDeliveryDate;
    echo $rate->maxEstimatedDeliveryDate;

    // Check rate recommendations
    if (in_array('CHEAPEST_RATE', $rate->rateRecommendation ?? [])) {
        echo "This is the cheapest option!";
    }
}
```

### Get Shipping Quote

[](#get-shipping-quote)

```
// Retrieve an existing shipping quote
$quote = Ebay::logistics()->getShippingQuote($shippingQuoteId);

echo $quote->shippingQuoteId;
echo $quote->orderId;

foreach ($quote->rates ?? [] as $rate) {
    echo $rate->rateId;
    echo $rate->carrierId;
    echo $rate->shippingCarrierCode;
}
```

### Create Shipment from Quote

[](#create-shipment-from-quote)

```
// Select a rate and create the shipment
$rateId = $quote->rates[0]->rateId; // Pick the first rate

$shipment = Ebay::logistics()->createFromShippingQuote([
    'shippingQuoteId' => $quote->shippingQuoteId,
    'rateId' => $rateId,
    'labelSize' => '4"x6"',
    'labelCustomMessage' => 'Thank you for your purchase!',
]);

echo $shipment->shipmentId;
echo $shipment->shipmentTrackingNumber;
echo $shipment->labelStatus; // OPEN, PURCHASED, EXPIRED, CANCELLED
echo $shipment->creationDate;
echo $shipment->labelExpirationDate;
```

### Download Shipping Label

[](#download-shipping-label)

```
// Download label as PDF (default)
$labelPdf = Ebay::logistics()->downloadLabelFile($shipment->shipmentId);
file_put_contents('shipping-label.pdf', $labelPdf);

// Download label as ZPL (for thermal printers)
$labelZpl = Ebay::logistics()->downloadLabelFile(
    $shipment->shipmentId,
    'application/zpl'
);
file_put_contents('shipping-label.zpl', $labelZpl);
```

### Get Shipment Details

[](#get-shipment-details)

```
// Retrieve shipment information
$shipment = Ebay::logistics()->getShipment($shipmentId);

echo $shipment->shipmentId;
echo $shipment->shipmentTrackingNumber;
echo $shipment->labelStatus;
echo $shipment->labelCustomMessage;

// Access rate details
echo $shipment->rate?->shippingServiceCode;
echo $shipment->rate?->shippingCost?->value;
echo $shipment->rate?->carrierId;

// Access addresses
echo $shipment->shipFrom?->fullName;
echo $shipment->shipFrom?->contactAddress?->city;
echo $shipment->shipTo?->fullName;
echo $shipment->returnTo?->contactAddress?->addressLine1;
```

### Cancel Shipment

[](#cancel-shipment)

```
// Cancel a shipment before label expiration
Ebay::logistics()->cancelShipment($shipmentId);

// After cancellation, labelStatus changes to CANCELLED
$shipment = Ebay::logistics()->getShipment($shipmentId);
echo $shipment->labelStatus; // CANCELLED
```

### Complete Workflow Example

[](#complete-workflow-example)

```
// Step 1: Create shipping quote
$quote = Ebay::logistics()->createShippingQuote([
    'orderId' => '12-12345-12345',
    'packageSpecification' => [
        'dimensions' => ['length' => '10', 'width' => '10', 'height' => '5', 'unit' => 'INCH'],
        'weight' => ['value' => '2', 'unit' => 'POUND'],
    ],
    'shipFrom' => [
        'fullName' => 'Your Store',
        'contactAddress' => [
            'addressLine1' => '123 Warehouse Rd',
            'city' => 'Los Angeles',
            'stateOrProvince' => 'CA',
            'postalCode' => '90001',
            'countryCode' => 'US',
        ],
    ],
    'shipTo' => [
        'fullName' => 'Customer Name',
        'contactAddress' => [
            'addressLine1' => '789 Customer St',
            'city' => 'New York',
            'stateOrProvince' => 'NY',
            'postalCode' => '10001',
            'countryCode' => 'US',
        ],
    ],
]);

// Step 2: Find the cheapest rate
$cheapestRate = null;
$lowestCost = PHP_FLOAT_MAX;

foreach ($quote->rates ?? [] as $rate) {
    $cost = (float) ($rate->shippingCost?->value ?? 0);
    if ($cost < $lowestCost) {
        $lowestCost = $cost;
        $cheapestRate = $rate;
    }
}

// Step 3: Create shipment with selected rate
$shipment = Ebay::logistics()->createFromShippingQuote([
    'shippingQuoteId' => $quote->shippingQuoteId,
    'rateId' => $cheapestRate->rateId,
    'labelSize' => '4"x6"',
]);

// Step 4: Download and save label
$labelPdf = Ebay::logistics()->downloadLabelFile($shipment->shipmentId);
$filename = "label-{$shipment->shipmentId}.pdf";
Storage::put("shipping-labels/{$filename}", $labelPdf);

// Step 5: Update order with tracking number
Ebay::fulfillment()->createShippingFulfillment($quote->orderId, [
    'lineItems' => [/* ... */],
    'shippedDate' => now()->toIso8601String(),
    'shippingCarrierCode' => $shipment->rate?->shippingCarrierCode,
    'trackingNumber' => $shipment->shipmentTrackingNumber,
]);

Log::info('Shipping label created', [
    'shipment_id' => $shipment->shipmentId,
    'tracking_number' => $shipment->shipmentTrackingNumber,
    'cost' => $shipment->rate?->shippingCost?->value,
]);
```

### OAuth Scope

[](#oauth-scope)

Logistics API requires the following OAuth scope:

- **All operations**: `https://api.ebay.com/oauth/api_scope/sell.logistics`

Add to `config/ebay.php`:

```
'scopes' => [
    'https://api.ebay.com/oauth/api_scope/sell.logistics',
    // ... other scopes
],
```

Message API
-----------

[](#message-api)

### Get Conversations

[](#get-conversations)

```
use Tigusigalpa\Ebay\Enums\{ConversationType, ConversationStatus};

$result = Ebay::message()->getConversations([
    'conversation_type' => ConversationType::FROM_MEMBERS->value,
    'conversation_status' => ConversationStatus::UNREAD->value,
    'limit' => 25,
]);

foreach ($result['conversations'] as $conversation) {
    echo $conversation->conversationTitle;
    echo $conversation->latestMessage?->messageBody;
}
```

### Send Message

[](#send-message)

```
// Start new conversation
$message = Ebay::message()->sendMessage([
    'otherPartyUsername' => 'buyer_username',
    'messageText' => 'Thank you for your question.',
    'reference' => [
        'referenceId' => '123456789',
        'referenceType' => 'LISTING',
    ],
]);

// Reply to conversation
$message = Ebay::message()->sendMessage([
    'conversationId' => 'c1234567890',
    'messageText' => 'Here is the information you requested.',
]);
```

### Manage Conversations

[](#manage-conversations)

```
// Mark as read
Ebay::message()->updateConversation([
    'conversationId' => 'c1234567890',
    'conversationType' => ConversationType::FROM_MEMBERS->value,
    'read' => true,
]);

// Archive multiple conversations
$result = Ebay::message()->bulkUpdateConversation([
    'conversations' => [
        [
            'conversationId' => 'c1111111111',
            'conversationType' => ConversationType::FROM_MEMBERS->value,
            'conversationStatus' => 'ARCHIVE',
        ],
    ],
]);
```

Working with Marketplaces
-------------------------

[](#working-with-marketplaces)

```
use Tigusigalpa\Ebay\Enums\Site;

// Set marketplace
Ebay::setSite(Site::UK);
Ebay::setSite(Site::GERMANY);
Ebay::setSite(Site::AUSTRALIA);

// Marketplace information
$site = Site::US;
$site->title();        // "United States"
$site->code();         // "us"
$site->url();          // "https://ebay.com"
$site->locale();       // "en-US"
$site->marketplace();  // "EBAY_US"
$site->currency()->symbol(); // "$"

// Find by code
$site = Site::fromCode('uk');           // Site::UK
$site = Site::fromMarketplace('EBAY_DE'); // Site::GERMANY

// List on multiple marketplaces
foreach ([Site::UK, Site::GERMANY, Site::FRANCE] as $site) {
    Ebay::setSite($site)->trading()->addFixedPriceItem($itemData);
}
```

Enums and DTOs
--------------

[](#enums-and-dtos)

Package uses PHP 8.1 Enums for type safety:

```
use Tigusigalpa\Ebay\Enums\{
    Site,
    Currency,
    ListingStatus,
    OrderStatus,
    PaymentStatus,
    ListingType,
    ReasonForRefundEnum,
    DisputeStatusEnum,
    EvidenceTypeEnum,
    SellerDecisionEnum
};

// Currency
$currency = Currency::USD;
$currency->symbol();      // "$"
$currency->htmlEntity();  // "&#36;"
$currency->title();       // "US Dollar"

// Listing Status
$status = ListingStatus::ACTIVE;
$status->title();         // "Active"
$status->description();

// Listing Type
$listingType = ListingType::FIXED_PRICE;
$listingType->description(); // "Buy It Now format with a fixed price"

// Fulfillment API Enums
$reason = ReasonForRefundEnum::BUYER_CANCEL;
$reason->title();         // "Buyer Cancel"

$disputeStatus = DisputeStatusEnum::OPEN;
$disputeStatus->title();  // "Open"

$evidenceType = EvidenceTypeEnum::PROOF_OF_DELIVERY;
$evidenceType->title();   // "Proof of Delivery"
```

### DTOs

[](#dtos)

```
use Tigusigalpa\Ebay\Http\Resources\{Order, Item};
use Tigusigalpa\Ebay\Http\Resources\Fulfillment\{
    Order as FulfillmentOrder,
    ShippingFulfillment,
    PaymentDispute
};

// Trading API DTOs
$xml = Ebay::trading()->getOrders();
foreach ($xml->OrderArray->Order as $orderXml) {
    $order = Order::fromXml($orderXml);

    echo $order->orderId;
    echo $order->total;
    echo $order->orderStatus->title();
}

// Fulfillment API DTOs (immutable with readonly properties)
$order = Ebay::fulfillment()->getOrder('12-34567-89012');

// Access nested DTOs
echo $order->buyer?->username;
echo $order->pricingSummary?->total?->value;
echo $order->pricingSummary?->total?->currency;

// Line items
foreach ($order->lineItems ?? [] as $lineItem) {
    echo $lineItem->title;
    echo $lineItem->lineItemCost?->value;
    echo $lineItem->quantity;
}

// Payment disputes
$dispute = Ebay::fulfillment()->getPaymentDispute('5001234567890');
echo $dispute->paymentDisputeStatus?->title();
echo $dispute->amount?->value;

// All DTOs use static fromArray() factory method
$orderData = ['orderId' => '12-34567-89012', /* ... */];
$order = FulfillmentOrder::fromArray($orderData);
```

Error Handling
--------------

[](#error-handling)

```
use Tigusigalpa\Ebay\Exceptions\{EbayApiException, AuthenticationException, InvalidConfigurationException};

try {
    $orders = Ebay::trading()->getOrders();
} catch (AuthenticationException $e) {
    Log::error('eBay auth failed', [
        'error_code' => $e->getErrorCode(),
        'message' => $e->getMessage(),
    ]);
} catch (EbayApiException $e) {
    foreach ($e->getErrors() as $error) {
        echo $error['code'] . ': ' . $error['message'];
    }
} catch (InvalidConfigurationException $e) {
    Log::error('Invalid eBay configuration', ['message' => $e->getMessage()]);
}
```

Optimization
------------

[](#optimization)

### Caching

[](#caching)

```
// config/ebay.php
'cache' => [
    'enabled' => true,
    'ttl' => 3600,
],
```

### Rate Limiting

[](#rate-limiting)

```
RateLimiter::attempt('ebay-api', $perMinute = 5000, function() {
    // API calls
});
```

### Queues

[](#queues)

```
dispatch(new SyncEbayOrdersJob($dateRange));
dispatch(new UpdateInventoryJob($products));
```

### Batch Processing

[](#batch-processing)

```
$itemIds = ['123', '456', '789'];
foreach ($itemIds as $itemId) {
    $items[] = Ebay::trading()->getItem($itemId);
    usleep(100000); // Rate limiting
}
```

Testing
-------

[](#testing)

```
composer test

# Unit tests only
./vendor/bin/phpunit tests/Unit

# Feature tests only
./vendor/bin/phpunit tests/Feature
```

FAQ
---

[](#faq)

**How to get API credentials?**

Register at [eBay Developers Program](https://developer.ebay.com/), create application and get App ID, Cert ID, Dev ID, RuName.

**Can I use for dropshipping?**

Yes. Package is suitable for order automation, inventory, and listings.

**What's the difference between Trading API and Commerce API?**

- **Trading API (XML)** — legacy API for core operations (listings, orders, categories)
- **Commerce API (REST)** — modern REST API for inventory, fulfillment, and new features

**How to switch to production?**

Set `EBAY_ENVIRONMENT=production` in `.env` and add production credentials.

**How to handle rate limits?**

Use Laravel Rate Limiter or add `usleep()` between requests.

Troubleshooting
---------------

[](#troubleshooting)

**"Missing required configuration"**

Check that all credentials are set in `.env`:

```
EBAY_SANDBOX_APP_ID=your-app-id
EBAY_SANDBOX_CERT_ID=your-cert-id
EBAY_SANDBOX_DEV_ID=your-dev-id
EBAY_SANDBOX_RUNAME=your-runame
```

**OAuth token expired**

Package refreshes tokens automatically. Ensure refresh token is set:

```
Ebay::setRefreshToken($refreshToken, $expiresAt);
```

**XML parsing errors**

Enable logging in `config/ebay.php`:

```
'logging' => ['enabled' => true],
```

Support
-------

[](#support)

- **Wiki**: [Documentation &amp; Guides](https://github.com/tigusigalpa/ebay-php/wiki)
- **GitHub Issues**: [tigusigalpa/ebay-php/issues](https://github.com/tigusigalpa/ebay-php/issues)
- **Discussions**: [GitHub Discussions](https://github.com/tigusigalpa/ebay-php/discussions)
- **Email**:

eBay Documentation
------------------

[](#ebay-documentation)

- [Trading API Reference](https://developer.ebay.com/devzone/xml/docs/Reference/ebay/index.html)
- [Commerce API Reference](https://developer.ebay.com/api-docs/commerce/static/overview.html)
- [Fulfillment API Reference](https://developer.ebay.com/api-docs/sell/fulfillment/resources/methods)
- [Logistics API Reference](https://developer.ebay.com/api-docs/sell/logistics/resources/methods)
- [OAuth 2.0 Guide](https://developer.ebay.com/api-docs/static/oauth-tokens.html)
- [Error Messages](https://developer.ebay.com/devzone/xml/docs/Reference/ebay/Errors/errormessages.htm)
- [API Rate Limits](https://developer.ebay.com/support/app-check)

Contributing
------------

[](#contributing)

```
git clone https://github.com/tigusigalpa/ebay-php.git
cd ebay-php
composer install
composer test
composer check-style
```

Requirements:

- PSR-12
- Tests for new features
- PHPDoc with links to eBay API docs
- Strict typing

License
-------

[](#license)

MIT. See [LICENSE](LICENSE).

Author
------

[](#author)

**Igor Sazonov**

- GitHub: [@tigusigalpa](https://github.com/tigusigalpa)
- Email:

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md).

###  Health Score

41

—

FairBetter than 88% of packages

Maintenance95

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~13 days

Total

4

Last Release

53d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/76c3a1d93c3213a8a22b4b637708d8b66a1ba3a5252624046cae7683a198b3a8?d=identicon)[tigusigalpa](/maintainers/tigusigalpa)

---

Top Contributors

[![tigusigalpa](https://avatars.githubusercontent.com/u/2721390?v=4)](https://github.com/tigusigalpa "tigusigalpa (15 commits)")

---

Tags

ebayebay-apiebay-api-integrationebay-api-wrapperebay-sdkecommercelaravelphpapilaraveloauthebaytradingcommerce

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tigusigalpa-ebay-php/health.svg)

```
[![Health](https://phpackages.com/badges/tigusigalpa-ebay-php/health.svg)](https://phpackages.com/packages/tigusigalpa-ebay-php)
```

###  Alternatives

[auth0/login

Auth0 Laravel SDK. Straight-forward and tested methods for implementing authentication, and accessing Auth0's Management API endpoints.

2745.0M3](/packages/auth0-login)[kovah/laravel-socialite-oidc

OpenID Connect OAuth2 Provider for Laravel Socialite

2073.7k](/packages/kovah-laravel-socialite-oidc)[truckersmp/steam-socialite

Laravel Socialite provider for Steam OpenID.

1516.7k](/packages/truckersmp-steam-socialite)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)