Storesome Listing Products

The purpose of this page is to specify in detail the process of creating and updating product content on the Storesome platform

API Docs: https://storesome-test-seller-api.azurewebsites.net/index.html - Changed URL to test environment.

API Call: POST /api/listings/integration - for creation; PUT /api/listings/integration/{id} - for update

type: multipart/form-data

To create and update product data on the Storesome platform we need to follow the same model described below. The difference is that to update we have to do it listing ID by ID following the API calls structure

The general product structure of Storesome follows as similar logic as in Hemisphere - it is broken in two sections - Listing (as called in Storesome), which holds all the generic information (title, description, attributes, images etc.) and Product, which holds the unique values (SKU, Quantity and Price, variation specifics). An important specific before we move to the mapping is that even if we are creating a single SKU on Storesome it still needs a Product associated to the listing (the Product acts almost as the Offer in these cases). Depending on the taxonomy itself a “variation” option can be a mandatory field even if it is only a single SKU listing (example - Colour is a mandatory field in the taxonomy)

Example call:

{
  "id": 0,
  "listingIdentifier": "string",
  "title": "string",
  "description": "string",
  "shortDescription": "string",
  "vat": 0,
  "createdBy": "string",
  "modifiedBy": "string",
  "countryCode": "string",
  "countryId": 0,
  "imageURL": "string",
  "categoryId": 0,
  "sellerId": 0,
  "returnPolicy": "string",
  "shippingType": 1,
  "conditionId": 0,
  "categoryAttributes": [
    {
      "id": 0,
      "value": "string",
      "isMandatory": true
    }
  ],
  "products": [
    {
      "id": 0,
      "sku": "string",
      "gtin": "string",
      "mainImageURL": "string",
      "canBeDeleted": true,
      "quantity": 0,
      "sellerId": 0,
      "price": 0,
      "specialPrice": 0,
      "specialPriceStartDate": "2021-08-16T06:16:02.905Z",
      "specialPriceEndDate": "2021-08-16T06:16:02.905Z",
      "imageUrls": [
        {
          "url": "string"
        }
      ],
      "productVariantProduct": [
        {
          "id": 0,
          "value": "string",
          "isMandatory": true
        }
      ]
    }
  ],
  "shippings": [
    {
      "shippingId": 0,
      "shippingName": "string",
      "isActive": true,
      "price": 0
    }
  ]
}

Mapping

Item > SKU (if single) | | | title | | | Item Account > Title | | | description | | | Item Account > Description | Mapping for Design template should happen in this field | | shortDescription | | | N/A | Field not used at the moment | | vat | | | Item Account > VAT | If negative value still pass as 0 | | createdBy | | | N/A | | | modifiedBy | | | N/A | | | countryCode | | | N/A | | | countryId | | | N/A | | | imageURL | | | The best leading image we’ve determined for the whole listing as per the product abstraction logic | We have to send an image as a listing image. We have our structure of picking the ONE image that needs to lead where requested, this is what we need here As per the abstraction picked from Item > {{images}} or Item Account Storesome > {{images}} Depending on the available images we should pick the Main image from Item Account Storesome or Main/Listing image from Item. For more info please see here: https://wearepentagon.atlassian.net/wiki/spaces/HEMI/pages/1494482956/Product+Listing+general+requirements#Images-management | | categoryId | | | Item Account > Primary Category ID | | | sellerId | | | N/A | | | returnPolicy | | | N/A | | | shippingType | | | N/A | | | conditionId | | | Item > Condition ID | Map Hemi statuses in the following Way Hemi = Storesome 1000 = 1 1500 = 2 3000 = 3 2500 = 4 2000 = 5 7000 = 6 | | categoryAttributes | | | N/A | | | | id | | Item Account > Item Specifics Key | ID’s and Values are to be mapped through the taxonomy. In Hemi we are expecting to have the human readable value of an Attribute and its value | | | value | | Item Account > Item Specifics Value | ID’s and Values are to be mapped through the taxonomy. In Hemi we are expecting to have the human readable value of an Attribute and its value | | | isMandatory | | N/A | | | products | | | | | | | id | | Item Account Storesome > Product ID | Don’t send “ID” field in the Create flow, pick from the mapped field for Update | | | sku | | Item > SKU | | | | gtin | | Item > EAN OR Item > UPC OR Item > Barcode | The first that is filled in | | | mainImageURL | | The best picture for the specific item we’ve determined from the product abstraction logic | As per the abstraction picked from Item > {{images}} or Item Account Storesome > {{images}} Depending on the available images we should pick the Main image from Item Account Storesome or Main image from Item. For more info please see here: https://wearepentagon.atlassian.net/wiki/spaces/HEMI/pages/1494482956/Product+Listing+general+requirements#Images-management | | | canBeDeleted | | N/A | | | | quantity | | Item Account > Quantity | | | | sellerId | | N/A | | | | price | | Item Account > StartPrice OR Item Account RRP | In the cases we have both StartPrice and RRP we want to send RRP as price and the StartPrice in the following Storesome field “specialPrice”. If we don’t have an RRP we want to send only “price” | | | specialPrice | | Item Account > StartPrice | Conditional - see “price” Also if Promotions are ready they should take over here | | | specialPriceStartDate | | Item Account Storesome > StartDate OR DEFAULT (NOW) | | | | specialPriceEndDate | | Item Account Storesome > EndDate OR DEFAULT (NOW+2years) | | | | imageUrls | | N/A | | | | | url | All other product specific images we have based on the products abstraction selection | As per the abstraction picked from Item > {{images}} or Item Account Storesome > {{images}} Depending on the available images we should pick the More Picture URLs from Item Account Storesome or More Picture URLs from Item. For more info please see here: https://wearepentagon.atlassian.net/wiki/spaces/HEMI/pages/1494482956/Product+Listing+general+requirements#Images-management | | | productVariantProduct | | | | | | | id | Item Account > Variation Specifics Key | ID’s and Values are to be mapped through the taxonomy. In Hemi we are expecting to have the human readable value of a Variation Option and its value | | | | value | Item Account > Variation Specifics Value | ID’s and Values are to be mapped through the taxonomy. In Hemi we are expecting to have the human readable value of a Variation Option and its value | | | | isMandatory | N/A | | | shippings | | | N/A | There can be multiple Shippings. For the pervious field pick the value from the first one. Here we can flesh out all of them | | | shippingId | | Account Storesome Shipping Services > Shipping Id | New field Please see Additional Information for the shipping methods in general | | | shippingName | | Item Account > Shipping Template > Shipping Method > Shipping Service OR Account > Shipping Template (default) > Shipping Method > Shipping Service | Please see Additional Information for the shipping methods in general | | | isActive | | true/false | Please see Additional Information for the shipping methods in general | | | price | | Item Account > Shipping Template > Shipping Method > Shipping Service Cost OR Account > Shipping Template (default) > Shipping Method > Shipping Service Cost | |

Additional Information

• Creation of Products in Storesome can be done only one by one or via this call or an upload via CSV file and then pull all listings for a mapping process. At the moment we will implement only the API JSON upload one by one
• Expectation is that as a response on each create we will receive only the Listing ID. As the Product IDs are mandatory for any further updates we need to incorporate the GET /api/listings/{id} with which we want to get the productIDs by the already received ListingID, store them in the Item Account Storesome > ProducID field so they can be used for any update We are still putting the product as published and active if successfully created as it is already trading If we have an update that needs to be pushed but we don’t have productIDs we want to set an error on the Listing so we know that this needs to be checked For every case where we can’t download ProductIDs we need to store how many times it has happened and make an exponential progression that sends error mails to Angel Sveshtnikov (Unlicensed)
• Any field that we don’t have info for (all the N/As from above and the IDs in the Create step) are not to be passed at all as fields in the request
• Shippings Storesome allows a specific number of shipment services (currently 3) on each product. Those are controlled by the Type but are in reality always present all of them. This means that if we just stop updating one of the 3 it will keep its latest update and potentially be available with that old value when we don’t want it to be available at all (because we’ve dropped it from our template). Best way to handle this is to have a place to keep all shipping services that the specific Storesome site provides (every Storesome site is a separate account for us). These services should be created as part of the setup for the Storesome Account. Then we have to track what is created as shipment methods in the Shipping Template that is applied to the product and map the “Shipping Service” field (from the Shipping Method) with “Name” from the Storesome Shipping Services that we’ve created as available. For every method that we map we should pass “true” for the isActive filed in the product payload to Storesome. For every “Storesome Shipping Service” that we can’t map (is not present in the Shipping Methods of the template) we should send “false”. As already suggested this setup should happen via a new table under Account Storesome (Account Storesome Shipping Service) that will hold the necessary information (as multi records) for each Storesome service. The table should hold the Names of the Services, their type (an enumeration value field to ensure the 3 services of Storesome are prioritised the right way one over the other) and the id of the shipping service. Validations:
  • The matching between Shipping Template > Shipping Method and Account Storesome Shipping Service should happen via the the respective “Shipping Service” and “Name” fields
  • If we don’t have a match for any of the Shipping Methods within the applied Shipping Template we should stop the payload to Storesome and in Hemisphere store an error that there are no available shipping methods for this product
  • If we have even a single Shipping Method in the Shipping Template that can’t be matched with what is set in the Account Storesome Shipping Services we should stop the payload to Storesome and in Hemisphere store an error that there is a wrong Shipping Template
  • For every Storesome Shipping Service we don’t have as a set Shipping Method within the Shipping template within the payload to Storesome we should send “false” as “isActive” and send a 0.00 price

NOTE - If we are doing this the right way we should build the Storesome integration as a connector that we can easily extend / replicate / add to for multiple different MPs as we might have multiple store some sites on the same Hemi instance the same way we have for Mirakl

Taxonomy choose

As we need to support different Storesome stores connection from the same Hemi we need the option not only to store different taxonomies but properly map to them and pick the right one (standard validations as per Product abstractions and above descriptions are not changing)

The most important thing is how we will differentiate the actual taxonomies based on the different Storesome stores (which can be found here). The same model should be adopted in the listing create and update to pick the right taxonomy before we start the actual standard validations. Once taxonomy is picked everything should run as per the currently described and developed functionality