ocyan.plugin.ebay

MandelBlogStack contract

This optional backend integration synchronizes Oscar catalogue products and stock with eBay's Trading API. It owns eBay credentials/token persistence, listing and inventory sync queues, eBay category/item-specific data, order import, and the management commands that explicitly start those workflows. It does not own checkout, payments, search infrastructure, deployment, backups, or the MandelBlog frontend/theme system.

The data flow is deliberately asynchronous: product/stock changes create ListingSync/InventorySync records; a scheduled spooler consumes bounded batches and retries failed calls. eBay listing/order responses are translated back into the plugin's models and Oscar entities. Wagtail/Oscar integration and the certified search/catalogue packages remain dependencies, not duplicated implementations.

Configuration is supplied through the Ocyan ebay settings object (app/dev/ cert identifiers, redirect name, site/country, policy IDs, sandbox flag, refresh limits, and sync attributes). Sandbox is the default and synchronization is disabled by default. Tokens are stored in the database and must never be committed to source or fixtures. Consumers should use environment-backed Ocyan configuration and rotate eBay consent approximately yearly according to eBay's authorization policy.

Supported certification matrix: Python 3.12–3.13, Django/Oscar versions supported by the certified Ocyan foundation packages, ebaysdk 2.x, and xmltodict 0.13+. Wheel and sdist validation is artifact-only; namespace imports resolve from installed site-packages. Legacy frontend classes/templates are temporary compatibility and are not the permanent MandelBlog theme contract.

Certification preserved the existing Trading API choice (required to update manually-created listings), sync retry semantics, migrations, fixtures, and management commands. It modernized PEP 621/PEP 420 packaging, bounded certified dependencies, artifact-based Jenkins validation, and removed credential-like values from tests/fixtures. Stable release evidence is recorded in the engineering-audit repository.

API limitations and design of this plugin

The ebay api is very limited compared to what is possible with oscar. Besides that we can only do 5000 requests per day by default.

That is why i designed the following structure:

• when a object is saved there will be a sync object created. Conditions will determine which call is made to ebay.
• There runs a cronjob that will get the first 100 syncs and tries to make the call to ebay.
• when they fail we will try them another 10 times.

The kind of objects that have a trigger are product and stockrecord. This way we can configure individual refresh rates for product and stock records.

The reason i chose the trading api and not the more advanced rest api is because we needed to update existing listings that are created by hand which is impossible with the rest api.

if 5000 requests per day are not enough we can let ebay approve our code and increase our rate limit.

Configuration & Authentication

Before we can access te users ebay account with our application the user have te give our application consent to operate on their behalve on ebay.

Configuration

To get user consent we have to fill in the following keys and id's

• Redirect URL name
• App ID
• Dev ID
• Cert ID
• Site ID These can be found here: https://developer.ebay.com/my/keys
  https://developer.ebay.com/my/auth?env=sandbox&index=0 https://developer.ebay.com/DevZone/XML/docs/Reference/eBay/types/SiteCodeType.html

These are all ocyan.json settings. By default we do requests to the sandbox, which is also an ocyan.json setting

Authentication

After we have filled in these settings the user must give their consent. Log in to the wagtail admin and go to settings -> ebay token settings

The token is valid for about a year and these steps must be repeated to renew the token.

before going further it is a good idea to also search for the return & shipping policy id's These must be entered in the ocyan.json and are send with every listing call. These can be found on the account of the ebay seller. if he does not have one he must create them.

Retreiving Existing Ebay Listings

Before retreiving existing listings we have to make sure they will not be updated directly when we are importing them. There for you must make sure the enable_sync setting in the ocyan.json is set to False, (this is the default setting)

• First we need to import the ebay categories and there corresponding required specifics. for the ebay.co.uk marketplace there is already a fixture generated with the taxonomy api. This file can be used with the ebay_import_categories.py to import the categories and specifics. The fixture is located in ocyan/plugin/ebay/fixtures/ebay/ebay_gb_categories.json

• After this we have to populate every product class with a few attributes that are used by this plugin. This managemend command is called ebay_populate_attributes. The command wil also populate the ebay sync attribute with the code used in the EBAY_ATTR_SYNC setting. If products already have this attribute make sure the setting is set to the correct attribute code before running this command.

• Now we can retreive the current existing ebay listings with the ebay_import_listings command. You have to pass a number as argument, this number means until how many days ago to retreive the listings. It can only retreive listings up until 120 days before the given day.

To sync existing products i've created a listing model with an ebay_id and active status.

Existing listings always have an ebay_id we must search in our database for products that have a matching upc or title. This works very effectively for electricals but maybe in a future update we can also search voor other matching fields.

Creating A Listing.

to create a listing there are a lot of fields required.

• country
• currency
• quantity
• listduration (always GTC)
• startprice
• title
• primarycategory id
• Condition (always new)
• Description
• At least one picture
• Location
• Required item specific type (detirmend by category)

When a product does not yet have an active listing and the ebay_sync attribute is set to True, i assume a listing with the save product must be created.

The Category detirmens which attributes are requried for the listing, when these requirements are not met the ebay listing wil not be created. The category is an model in our database and has a relation to the required specifics.

See item specifics for more information.

Item Specifics

A lot of categories in ebay have required item specifics, this is what we call product attributes in Oscar. These are detirmend by the category and are saved in a model.

These categories and specifics differ per ebay marketplace, so ebay.nl can have different categories then ebay.co.uk. These categories and specifics can be retreived with the taxonomy api.

child products require an attribute that distinguish them from each other. see parent & child products section for more information

Listing Details

is used to provide one or more product identifiers for a product, and if desired by the seller, eBay will use the identifier(s) of the product to try to match it to a defined product in the eBay catalog. If a seller's product is matched to an eBay catalog product, the product details associated with that catalog product will be prefilled for the listing. Product details defined for a catalog product include the product title, product description, product aspects, and stock image(s) of the product (if available).

Updating Listings

To update an active listing there must be an active listing in our database with an product that has the ebay_sync attribute set to True. When je save() a product all fields in ebay are updated. Attributes are only updated whene they are related to the ebay category.

You can't delete attributes because it is impossible to delete individual attributes. It is only possible to delete all attributes but some are required which still makes it impossible to delete all of them.

Delisting And Relisting

this you can do by enabling or disabling the ebay_sync attribute. When you relist a delisted listing the listing gets another ebay-id.

stock updates

These calls sit in another sync model so we can change the rate limit individually.

parent & child products

Child products are called variations in ebay, for these variations we pass the quantity and price.

Besides this we also have to indicate which attribute distinguishes the child from another child. To determine this a parent product must have the variation_specific_set attribute otherwise the listing will not be created or updated. The attributes in the varation_specific_set must exist and have a value on the child proudct. If there are more attributes together that distinguish a child you must seperate them by ; in de the variation_specific_set attribute e.g. color;size

all other attributes that are not in the variation_specific_set will be retreived from the parent product.

After the listing is created you cannot change the variation_specific_set or there corresponding values of the children. If you want to change an attribute of a child that is in variation_specific_set you must delete the child from ebay and then change it in the webshop.

Child products must always have stockrecord.

API call limit

Taxonomy API

The taxonomy api is a new rest api and for this plugin i needed to use the old trading api. On another branch called ebay_integration i've implemented the other taxonomy api. There is a managemend command that retreives all categories and specifics for the given marketplace and puts it in a json file

For EBAY_GB i've already retreived the categories and specifics, which we can use for london. theser are found in the fixtures directory

other site id's can be found here: https://developer.ebay.com/devzone/merchandising/docs/concepts/siteidtoglobalid.html

Common issues

• When you delist a parent product and delete a child product, then relist the parent you get a variation mismatch error and to solve this you must update the ebay listing by hand so it is the same as the product on the shop.