Marketplaces / OnBuy / Listings Management

Listings Management

The purpose of this page is to specify in detail the management of Listings through Hemisphere on OnBuy

Version Created / Updated by Notes
1.0 Danail Deltchev Initial Creation

As per our Products flow we should be “Creating” Listings only against products that are already not created on OnBuy

POST Create Listings

API Docs: https://docs.api.onbuy.com/#74424758-f3b2-4cc9-b4cb-f74878598d8f

API Call: https://api.onbuy.com/v2/listings

Purpose: Creating Listings against products we’ve already found existing on OnBuy

Fields and Specifics:

Name Type Required Details WAP Mapping WAP Notes
site_id integer YES target site. Default is 2000

Type:

integer

Example:

2000 | | | | By country of MP | As briefly discussed can be 2000 to start off as we are not expecting other OnBuy sites soon | | listings | array | YES | Key | Type | Required | Details | Expectation is that there should be no need of Master and Variant sections as OPC should be unique for every product and listings are created against an OPC | | | | | | opc | string | YES | OnBuy Product Code Type:

string

Example:

PN8JV6 | item_account > ChannelItemId | | | | | | condition | string | YES | condition of the listing Type:

string

Example:

poor

condition can be one of the following values: • new • good • average • poor | Item > Condition | Values mapping: • new: 1000, 1500 • good: 2000, 2500, 3000, 4000, 5000, 2750 • average: 6000 • poor: 7000 | | | | | price | decimal | YES | price of product in the listing Type:

decimal

Example:

9.99 | item_account > StartPrice | | | | | | stock | integer | NO | number of items in stock Type:

integer

Example:

8 | item_account > Quantity | | | | | | delivery_weight | integer | NO | weight of item in kilograms Type:

integer

Example:

16 | item > weight | | | | | | handling_time | integer | NO | number of days expected to fulfil the order Type:

integer

Example:

125 | item_account > DispatchTimeMax OR item_account > Shipping Template > DispatchTimeMax OR Account > Default Shipping Template > DispatchTimeMax | | | | | | free_returns | boolean | NO | are free returns are available? Type:

boolean

Example:

true

free_returns can be one of the following values: truefalse | N/A | | | | | | warranty | integer | NO | period in months a warranty is valid Type:

integer

Example:

7 | N/A | | | | | | condition_notes | array | NO | array containing details about the condition of the item Type:

array

Example:

[] | item_account > Condition Description | |

Note: Based on the “Products” information I am expecting we should be able to send with the Listing also “SKU”, “Delivery_Template_Id” and “Group_SKU” (please see the fields in Products mapping section). OnBuy have confirmed Listing within Product API and Listing API should act and point to the same things

Actions:

  1. Listings for creation should be picked only when the product has product_status = “product_created“ and has revise_item = “pending“ and ChannelItemId is not empty. Listings shouldn’t have a Queue so immediate response is expected for them
    1. If Success - set product_status to “product_published”, listing_status to “active“ and revise_item to “normal“
    2. If Error - set revise_item to “error“ and store the relevant error
  2. If end_item is set to 1 we should treat the Listing creation the same way just send 0 quantity and upon reading the result set end_item to 0
  3. In case any of the other flags, update_quantity and update_price was on “pending” we should set it to “normal” when reading the Listing Create response as there is no reason for them to be raised when we’ve just pushed a Listing with that information (especially if success)

PUT Update Listing

API Docs: https://docs.api.onbuy.com/#d5647dfd-7fe3-4938-9fff-cde71fb8d276

API Call: https://api.onbuy.com/v2/listings/by-sku

Purpose: The purpose of this call is to update Stock and Price. At the moment we are to treat it only as that. Expectation is that any other updates on the Listing section will happen with an attempt of a full product update including a listing section as well

Fields and Specifics

Name Type Required Details WAP Mapping WAP Notes
site_id integer YES default 2000

Type:

integer

Example:

2000 | | | | By country of MP | As briefly discussed can be 2000 to start off as we are not expecting other OnBuy sites soon | | listings | array | YES | Key | Type | Required | Details | As for the creation - no Master or Variant sections, just listings by SKU | | | | | | sku | string | NO | SKU of listing Type:

string

Example:

EXP-143-33S | item > SKU | | | | | | price | decimal | NO | price of item Type:

decimal

Example:

126.34 | item_account > StartPrice | | | | | | stock | integer | NO | number of items in stock Type:

integer

Example:

125 | item_account > Quantity | | | | | | boost_marketing_commission | decimal | NO | percentage Type:

decimal

Example:

14.83 | N/A | |

Actions:

  1. As the communication is synchronous we should be sending either price or stock or both depending on the raised flags
  2. If both flags are raised and we are sending information for both price and quantity in case of an error both should be set to error
  3. Updates are to be sent only for products that are with product_status = “product_published”
  4. If end_item is set to 1, as for every other MP, we want to send quantity 0 and by the result update the update_quantity flag as well.

DEL Listing removal

API Docs: https://docs.api.onbuy.com/#02725c00-6eaa-40a9-bcad-c53948b163aa

API Call: https://api.onbuy.com/v2/listings/by-sku

Purpose: To completely remove a listing from OnBuy

Fields and Specifics:

Name Type Required Details WAP Notes WAP Mapping
site_id integer YES default 2000

Type:

integer

Example:

2000 | By country of MP | As briefly discussed can be 2000 to start off as we are not expecting other OnBuy sites soon | | skus | array | YES | list of product SKU entries (string) Type:

array

Example:

[] | item > SKU | |

Actions:

  1. We should be removing listings only when the flag delete variation has been used
  2. Once a listing has been successfully deleted for the SKU we are to put the product back on a product_status = “product_created“ and listing_status = “inactive“
Is this article helpful?
0 0 0