Known API Issues and Errors

This page documents currently known issues and error responses encountered when working with the eBay API, including potential solutions.

• Error Code 20500
• The seller profile ID is not valid. / The seller is not BP opted in.

Error Code 20500

The error code 20500 indicates an internal system error on eBay’s side and is usually returned together with an HTTP 500 response. In most cases, this issue is beyond our control. When it occurs, there is nothing we can do except wait and hope that eBay resolves the underlying problem sooner rather than later.

The following requests are currently known to return a 20500 / HTTP 500 error:

• Rat\eBaySDK\API\AccountAPI\CustomPolicy\CreateCustomPolicy

Solution

In some cases, eBay returns a 20500 / HTTP 500 error for an invalid or incorrectly structured request payload, instead of responding with a proper HTTP 400 validation error.

To rule out this error, carefully compare the payload generated by the request constructor and / or the payload you provide manually with the official eBay API documentation. Don't worry, each request class includes a reference to the corresponding eBay API documentation page in its class-level docblock, allowing you to verify the related structure without additional searching.

Be aware that many requests do not accept a single $payload array. Instead, request data may be passed as individual constructor parameters, which are then mapped internally to params(), query(), body(), or even headers(), depending on eBay’s API requirements.

You can use the $client->inspect() method for debugging purposes.

If you identify an issue within the SDK itself, please report it by opening a GitHub issue or submitting a pull request. As a temporary workaround, you may also extract the affected request into your own project, instantiate it manually, and ensure that the resulting request payload matches the expected structure defined in the official documentation.

The seller profile ID is not valid. / The seller is not BP opted in.

This error occurs when the seller account is not enrolled in eBay’s Selling Policy Management program. It is currently known to affect the following requests:

• Rat\eBaySDK\API\AccountAPI\FulfillmentPolicy\CreateFulfillmentPolicy
• Rat\eBaySDK\API\AccountAPI\FulfillmentPolicy\UpdateFulfillmentPolicy
• Rat\eBaySDK\API\AccountAPI\FulfillmentPolicy\DeleteFulfillmentPolicy
• Rat\eBaySDK\API\AccountAPI\PaymentPolicy\CreatePaymentPolicy
• Rat\eBaySDK\API\AccountAPI\PaymentPolicy\UpdatePaymentPolicy
• Rat\eBaySDK\API\AccountAPI\PaymentPolicy\DeletePaymentPolicy
• Rat\eBaySDK\API\AccountAPI\ReturnPolicy\CreateReturnPolicy
• Rat\eBaySDK\API\AccountAPI\ReturnPolicy\UpdateReturnPolicy
• Rat\eBaySDK\API\AccountAPI\ReturnPolicy\DeleteReturnPolicy

Solution

To resolve this issue, ensure that your seller account is opted into the SELLING_POLICY_MANAGEMENT program. This can be done by calling the OptInToProgram endpoint. The following helper function demonstrates how to check the current opt-in status and enroll the account if necessary.

Once the account is successfully opted in, the affected policy-related requests should work as expected. Assuming eBay is having a good day.

use Illuminate\Support\Arr;
use Rat\eBaySDK\API\AccountAPI\Program\GetOptedInPrograms;
use Rat\eBaySDK\API\AccountAPI\Program\OptInToProgram;
use Rat\eBaySDK\Client;
use Rat\eBaySDK\Enums\ProgramType;

/**
 * Ensures that the SELLING_POLICY_MANAGEMENT program is enabled.
 * @return bool
 */
function ensure_selling_policy_management_program(): bool
{
    $client = app(Client::class);

    $response = $client->execute(new GetOptedInPrograms);
    if (!$response->ok()) {
        return false;
    }

    $programs = Arr::flatten($response->content()['programs'] ?? []);
    if (!in_array(ProgramType::SELLING_POLICY_MANAGEMENT->value, $programs)) {
        $response = $client->execute(
            new OptInToProgram(ProgramType::SELLING_POLICY_MANAGEMENT)
        );
        return $response->ok();
    } else {
        return true;
    }
}