Marketplaces / OnBuy / Products management

Products management

The purpose of this page is to describe how we should structure our general content management (listing and updates), through what statuses it should go and what information is needed

Version	Created / Updated by	Notes
1.0	Danail Deltchev	Initial Version
1.1	Danail Deltchev	Change in product Mappings: New fields for Documents, Videos and Technical Detail where we have a key/value pair are to be of type “ItemSpecifics” not “More Images”
Added technical details check for uniqueness
1.2	Danail Deltchev	Changes in:

• Get Products - due to OPCs not properly presented in Queue response for variants we need to Get them separately) • Create product - based on latest conversations we CAN NOT create/add variants to an already existing VariationGroupId and in case this is happening we need to send as new group • Update product - as we can’t add new variants to an existing one we need to skip them based on status. Also it was communicated to us we can’t push product updates to products not created by us, so this is to be tracked by Get products as well and taken in consideration by Update products | | 1.3 | Danail Deltchev | Changes in: • Update products - style of updating: when/how/what • Images handling - small change to what is allocated between variant and parent |

API docs: https://docs.api.onbuy.com/#products & https://docs.api.onbuy.com/#98f148b9-104d-41c4-b816-2980f6268d4d

The first section describes the flow of sending data and working with OnBuy’s batches. The second is the direct link to the Products management APIs section

A few things to be said initially before going into details

OnBuy operate on a catalogue base - meaning there is only one record per EAN in their system and different sellers can create listings against that product
Based on the above they operate on creating products and sending listings against them afterwards. The products can roughly be split into two sections Master and Variant. There are many tags that can be send either in one or the other or duplicated. Below you will see information where we should send different information to the best of my knowledge
On Buy work with unique codes called OPC (OnBuy Product Code) which is the equivalent of a ChannelItemId
We will heavily work with Product Status and Listing Status to maintain to the best of our ability knowledge at what stage is the product
If we are creating a variation product we will receive an OPC for the master (which is a nonexistent record in Hemisphere) and an OPC for every variant (both need to be stored)
Based on further investigation and conversations we’ve uncovered that specific sets of information can be updated and some can be updated only on a certain level. Distribution goes like this:
1. Parent level:
  1. Brand
  2. Category
  3. Name
2. Variant:
  1. MPN (in case the whole product has any variants)
  2. RRP (in case the whole product has any variants)
3. Both:
  1. Description
  2. Summary Points
  3. default_image
  4. additional_images
  5. features
  6. videos
  7. documents
  8. product_data
  9. technical_detail

Products flow - we want to follow MP best practices and optimise our processes at the same time. For OnBuy we want to do the following:

Call for EANs - If the EAN is present it should be respectively marked in Hemisphere to continue further communication with OnBuy without the need to create the product (note: if the product already exists we want to mark it as “not created by us” so we don’t send product updates for it later). This step is to be done only if the product is not marked as “created” in Hemisphere
If the product is not present we should proceed with sending all the information to OnBuy
1. Submit product data
2. Read initial validation - Error or Queued
3. Check Queue
4. Read final status - Error or Created
5. Read variant OPCs

GET Products:

API Docs: https://docs.api.onbuy.com/#c6ccd9b0-8e0f-4165-b65a-a6a520fe6c9d

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

Purpose: To retrieve by EAN already existing products on OnBuy to decide if product creation step is required OR download the OPCs of variants we’ve created

Fields and Specifics

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

Type:

integer

Example:

string

Example:

bar | N/A | | | | | | field | string | NO | defines which field the filter[query] should be matched with Type:

string

Example:

opc

integer

Example:

8 | N/A | | | limit | integer | NO | The number of results to return. Max value 100 Type:

integer

Example:

34 | | | | N/A | We are expecting a single result by Product_code | | offset | integer | NO | The batch of results to return Type:

integer

Example:

34 | | | | N/A | |

Actions:

To fire up this function we are looking for products on revise_item = “pending“, ChannelItemId = Empty value and product_status = “awaiting_creation“ or Empty value. We are to check every such item if it is present on OnBuy.
1. If it is present we should store it’s OPC in ChannelItemId and in item_account_onbuy.OPC, mark the product as not created by us in item_account_onbuy.dont_manage_content = “yes” and set the product_status to “product_created“
2. If it is not present we should prepare the item for creation step. The way I see it it should all happen together so if the product is not created on OnBuy it can directly be pushed for creation (stored and bundled for creation on multiple products at once). If decided we need to store in DB after the search operation we might need to add another product_status to perfectly capture this
The second option to check for OPC is if we have a product that is on revise_item = “normal“, ChannelItemId != Empty value, product_status = “product)published“ and item_account_onbuy.OPC = Empty value
1. If it is present we should store it’s OPC only in item_account_onbuy.OPC
2. If not present we should store an error on revise_item_error = “Variant OPC missing“

POST Product create:

API Docs: https://docs.api.onbuy.com/#4bb6d39a-c7c7-45a1-8a6c-d93edc47bba4

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

Purpose: Sending product data for creation to OnBuy

Note: Before reading the below:

In the WAP Notes there will be a list of where a section is expected if single or if Variant listing
All sections can be on Parent/Master section even if it is a variation but the following: Barcode, Listing details, Variant details
We want only the relevant images in the relevant section. We still want to associate more images to both Parent/Master and the Variant due to further uncovered information on how this is handled within OnBuy
It is possible that only Brand_name OR Brand_id is needed - we should test this - in both cases we will need to pull available brands down as part of the taxonomy
Variations in Hemisphere are recognised by the grouping element VariationGroup on item_account

Fields and Specifics:

Name	Type	Required	Details							WAP Mapping	WAP Notes
site_id	integer	YES	target site. Use the /v2/sites method to obtain a list of site IDs.

Type:

integer

Example:

integer

Example:

125 | | | | | | | item_account > Primary Category ID | Should always be on the Master section | | published | boolean | NO | specifies whether the product should be published to the site once it's created. Products not published will need to be completed through the SCP. This can be used to review the product before it is displayed publically. Please be aware that products that are not marked as published are automatically cleared from the system after 72 hours. Use 1 for published and 0 for not published. Type:

boolean

Example:

1 | | | | | | | 1 | Always Yes. We don’t want to have any manual steps in the process Should always be on the Master section | | product_name | string | YES | the name of the product Type:

string

Example:

bar | | | | | | | item_account > Title | Should always be on the Master section | | mpn | string | NO | manufacturer's product reference number Type:

string

Example:

array

Example:

array

Example:

[] | | | | | | | N/A | | | description | string | NO | a description of the product Type:

string

Example:

string

Example:

integer

Example:

string

Example:

foo | | | | item_account_onbuy > {{New Field}} Videos | Field like ItemSpecifics If variation listing should be checked for uniqueness on all variant participants. If all are the same push on Master level. If even one is different every single one should be on Variant level | | | | | url | string | NO | location of the video stream Type:

string

Example:

string

Example:

foo | | | | item_account_onbuy > {{New Field}} Documents | Field like ItemSpecifics If variation listing should be checked for uniqueness on all variant participants. If all are the same push on Master level. If even one is different every single one should be on Variant level | | | | | url | string | NO | location of this product document Type:

string

Example:

string

Example:

foo | | | | | | | item_account_onbuy > Main Image OR item > Listing Image OR item > Main Image | If item_account_onbuy has main images filled in we should use all images only from there . If not move to item based on the mapping order. We should always apply the following logic: if images on all products are the same put one default on the Master and the same on the Variants. If they are different chose the first for the Master and each Variant should have its own Main Image as default_image In the rare case there is a Listing Image it doesn’t need checks for uniqueness. Pick it as default for the Master. The Variants still get their respective Main Image as default_image | | additional_images | array | NO | string values of additional image urls Type:

array

Example:

[] | | | | | | | item_account_onbuy > more images OR item > more images | In case there are more images and they are the same across the whole variation listing we should send the same set of images for both the Parent/Master and each variant as part of the additiona_images section. If there is even one difference on Parent/Master level we should send a selection of only the different main_images as additional_images where for each Variant we are to send its own more_images as additional_images | | rrp | decimal | NO | Recommended Retail Price Type:

decimal

Example:

string

Example:

bar | | | | N/A | | | | | | value | string | NO | value of this paricular key/value pair Type:

string

Example:

foo | | | | N/A | | | | | | group | string | NO | name of a group which describes these attributes Type:

string

Example:

foo | | | | N/A | | | listings | array | NO | Key | Type | Required | Details | | | | This section can either be in the Master or Variant part of the API call depending if the product is Single or Variation listing | | | | | | new | array | NO | Key | Type | Required | Details | | | | | | | | | | sku | string | NO | product SKU Type:

string

Example:

string

Example:

decimal

Example:

integer

Example:

integer

Example:

integer

Example:

7 | N/A | | | | | | | | | free_returns | string | NO | specify whether to accept free returns; "yes" or "no" Type:

string

Example:

foo | N/A | | | | | | | | | warranty | integer | NO | number of months within which the warranty is valid Type:

integer

Example:

252 | N/A | | | | | | | | | delivery_template_id | integer | NO | overrides the default delivery template, for possible values @see # Type:

integer

Example:

array

Example:

[] | item_account > Condition Description | | | features | array | NO | Key | Type | Required | Details | | | | | | | | | | option_id | integer | NO | Use the /v2/categories/{{category_id}}/features method to obtain a list of valid features for the specified category. Type:

integer

Example:

16 | | | | item_account > Item Specifics | If MP taxonomy is present in DB make validations to push through. Otherwise send as is All same Attributes to go on Master level. Different Attributes to go on Variant levels (always only from IS, VS is another story) | | | | | name | string | NO | optionally specify a 'name' parameter to override the existing name. Type:

string

Example:

foo | | | | item_account > Item Specifics | If MP taxonomy is present in DB make validations to push through. Otherwise send as is All same Attributes to go on Master level. Different Attributes to go on Variant levels (always only from IS, VS is another story) | | | | | hex | string | NO | optionally specify a hexadecimal colour value Type:

string

Example:

bar | | | | N/A | | | technical_detail | array | NO | Key | Type | Required | Details | | | | | | | | | | detail_id | integer | NO | Use the /v2/categories/{{category_id}}/technical-details method to obtain a list of valid detail ids for the specified category Type:

integer

Example:

34 | | | | item_account_onbuy > {{New Field}} Technical Details | Field of type ItemSpecifics All same Technical Details to go on Master level. Different Technical Details to go on Variant levels | | | | | value | string | NO | the value of this key/value pair Type:

string

Example:

string

Example:

string

Example:

string

Example:

array

Example:

array

Example:

array

Example:

[] | | | | | Please see section Listings above for the available fields |

Note: Please have in mind that for the “Listing” section we should be able to also provide “condition” based on the “Listing Management” information. For the mapping options for that field please refer to the mentioned document. This is happening due to discrepancy in OnBuy’s documentation but they confirmed the Listings should behave the same in both APIs

Example JSON:

{
  "site_id": 2000,
  "category_id": "6112",
  "brand_name": "Superga",
  "product_name": "Superga - 2750-COTU-CLASSIC",
  "description": "Superga - 2750-COTU-CLASSIC-eu-46",
  "default_image": "https://app.onepatch.co.uk/assets/listingimages/full_24848_36707stock_product_image_98013_1118588329.jpg",
  "additional_images": [
    "https://app.onepatch.co.uk/assets/listingimages/full_24849_85615stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24850_36101stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24851_41457stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24852_58914stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24853_82840stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24854_14702stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24855_49201stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24856_49259stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24857_91717stock_product_image_98013_1118588329.jpg",
    "https://app.onepatch.co.uk/assets/listingimages/full_24858_64532stock_product_image_98013_1118588329.jpg"
  ],
  "published": 1,
  "variant_1": {
    "name": "Colour"
  },
  "variant_2": {
    "name": "Shoe Size"
  },
  "variants": [
    {
      "variant_1": {
        "name": "Burgundy"
      },
      "variant_2": {
        "name": "Size 6"
      },
      "listings": {
        "new": {
          "sku": "2750-COTU-CLASSIC_S000010-A01_BRIGHT-BLUE EU 46",
          "price": "53.1",
          "stock": 1
        }
      },
      "product_codes": [
        "5080449921406"
      ],
      "default_image": "https:\/\/tencate1952.co.uk\/wp-content\/uploads\/2018\/08\/3601-green-print-3.jpg",
      "features": [
        {
          "option_id": 125,
          "name": "Burgundy"
        },
        {
          "option_id": 111520
        }
      ]
    },
    {
      "variant_1": {
        "name": "Olive Green"
      },
      "variant_2": {
        "name": "Size 9"
      },
      "listings": {
        "new": {
          "sku": "1rdlrge",
          "price": "19.00",
          "stock": 3
        }
      },
      "product_codes": [
        "5042383257201"
      ],
      "default_image": "https:\/\/tencate1952.co.uk\/wp-content\/uploads\/2018\/08\/3601-green-print-3.jpg",
      "features": [
        {
          "option_id": 93,
          "name": "Olive Green"
        },
        {
          "option_id": 111526
        }
      ]
    }
  ]
}

Actions:

Once we’ve determined this product is not available on OnBuy we need to pick it up, bundle it with all others like it and send them for creation. This should either happen by the firs function gathering a list of all products that need to be sent or bi the newly set product_status that will be also on revise_item = “pending” so we can send the products.
Once we’ve sent the products we should either receive back success or Error
1. On Success we should store the Queue IDs to follow through and see the end result
2. On Error we should push it back to revise_item = “error” and store the relevant error (Note: if we use new product_status next time products go to “pending” they will skip the EAN check which can be both good and bad, TBD)
If we’ve had success we should start checking the progress of the Queue IDs and reflect back in Hemisphere once they are processed
1. On Success set the item_account to revise_item = “normal“, product_status = “product_published“, listing_status = “active“, the OPC in the ChannelItemId
2. On Error set the item_account to revise_item = “error“ and store the relevant error

Notes:

Due to the queue we can’t put all update fields to “normal” once the product is processed as there could’ve been quite a lot of changes while the product was created
If we are creating the product once completed we are setting everything (product_status and listing_status ) to end values as we are sending all the info and the product should be up and selling. In the case of a EAN already being present on OnBuy we will need an additional step to send and create just a listing (Please see “Listings management” section in the OnBuy Scope)
We can send a variation group for creation only once. If at a later stage there is an attempt of sending additional variants with the same VariationGroupId any such are to be automatically set on revise_item= “error“ with the message: “Additional variants can be added to the already created options. Please change VariationGroupId and send as additional group“

PUT Update Products

API Docs: https://docs.api.onbuy.com/#a3e00100-19e1-402e-a2ad-df0c95efdc78

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

Purpose: To update product records with information. Call is exactly the same as the POST Products call for creation with the difference that as this is a Batch update it needs to be wrapped in a “Products” section.

Recommendation as coming from OnBuy is to send an update for every OPC. Meaning a separate update for every variant we have and for the master.

We are to send for each OPC only the information that it holds based on the split as explained above in the Creation step and with the additional restrictions posed by OnBuy when updating (point 6 in the beginning of the document)

Notes:

OPC needs to be provided for every update call
After additional communication with OnBuy we’ve found we can’t add additional variants to a listing. This means we should be sending Product updates only for products that are on product_status= “product_published“. Any such (from the same VariationGroupId) that are not created should be skipped and is for the Create call to set them on Error
Also variation names and values can’t be changed once created through the API - can be skipped in the update information
Additionally for any such items that we don’t own the content management (based on item_account_onbuy.dont_manage_content= “yes“) we are to set on revise_item = “error“ with the message: “We don’t manage the content for this product. Only listing updates can be processed“

Is this article helpful?

0 0 0