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:
- Listings for creation should be picked only when the product has
product_status
= “product_created“ and hasrevise_item
= “pending“ andChannelItemId
is not empty. Listings shouldn’t have a Queue so immediate response is expected for them- If Success - set
product_status
to “product_published”,listing_status
to “active“ andrevise_item
to “normal“ - If Error - set
revise_item
to “error“ and store the relevant error
- If Success - set
- 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 - In case any of the other flags,
update_quantity
andupdate_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:
- As the communication is synchronous we should be sending either price or stock or both depending on the raised flags
- 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
- Updates are to be sent only for products that are with
product_status
= “product_published” - If
end_item
is set to 1, as for every other MP, we want to send quantity 0 and by the result update theupdate_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:
- We should be removing listings only when the flag delete variation has been used
- Once a listing has been successfully deleted for the SKU we are to put the product back on a
product_status
= “product_created“ andlisting_status
= “inactive“