Marketplaces / Shopify as Marketplace / Shopify Functional specification

Shopify Functional specification

General overview of the marketplace

Shopify platform does allow you to manage most of it's features using API.

Product listing, Order management, Stock management are all available over API.

Order management includes full and partial order management both for shipment and refund management.

Flows to be used

Product flows:	Order flows:	Other:
• Create products

• Update products • Update stock • Update price | • Download orders • Ship orders - initially full shipments only • Refund orders - initially full refunds only • Cancel orders - it will be added as second phase | • Taxonomy management - in the specific case "Collections" |

Authentication - specifics

Product flows - specifics

1. Product Creation -

Create Product logic:

Images specific:

Images have to be sent on a Product level in order for Shopify to upload them on their CDN. For each product no matter if it has variations or not we have to send ALL images (for each variation).

For variations we have to send a call after we create the products and variations that adds one image per Variant

To achieve that you need to go to this page: PUT Variant and use what is described in the "Add an existing image to an existing variant" example.

After the current logic which sends all pictures from all variations on product level we need to use the following logic for assigning pictures to variants:

IF main image is the same for all product variations THEN assign to each variant the first picture found in the more picture URLs field.

IF main image is different for each product variation THEN assign to each variant the main image.

Product data - Send all product data. In item specifics look for weight and brand those two need to be treated specifically as weight is mandatory and should be associated with weight field in Shopify and brand we want to send to Shopify as Vendor. Everything else from these two in item specific should be send as tag.

a. Single - If variation group is empty then product will be sent as single and only Item Specifics will be taken not .

b. Variation - If variation group is not empty all selected variants(list/update = yes) will be sent.

IF a variation has been created and another variant has been added to the already existing one update the whole product by adding the new variation

2. Product update -

Product update logic:

We should separate image update from all other product updates(agreed). As shopify doesn't allow us to update an image with a new one we should be clearing out all images before updating them (needs to be tested).

Full product update should send the update info about the product which is sent by the create product cron except for product images.

Image update should be sent separately and triggered only if explicitly specified.

~~First case to be tested: - didn't work~~

~~IF Image is available in "item" but is not available in "product account Shopify" then it gets selected for sending. We need to check if that will delete the other available images on Shopify.~~

~~If that case works then this is how we are going to be sending the images. If it doesn't work then we should consider the process to be in two steps:~~

Second case: this is the case we need to use

a . ~~We have to track if there are images to be added to the ones currently sent. This is going to be done by storing the image links and image id's returned by Shopify when we are creating products. They are being stored in "product account Shopify" in the field "product_images"~~

~~if YES then we just add the new images~~
~~if NO then we have to follow next steps~~

a. Add a flag in item_account_shopify named update_images if the flag is set to 0 then don't include the images in the product updates if the flag is set to 1 then follow next steps

b. Send an empty array which should delete all images

c. Send all images available for the product

After testing if first case works a decision can be made how to handle it properly.

Additional image logic: When we are listing a variation if all the images on the first sku are the same as on each of the following skus we have to be sending the images for the whole product from the first sku but skip the images for all of the following skus. This logic should be skipping the assigning of images to Variants as well.

Single - If variation group is empty do not send variation specifics, send only item specifics.

Variation - If not all variants have been selected for update(list/revise = yes) then only the information for the selected variant will be sent.

3. Stock updates - Use standard practice. Send the updates every time there is a change.

4. Price updates - Use standard practice. Send all updates every time there is a change.

5. Zero quantity updates - They should be sent with higher priority to all other stock updates.

6. Delist / Deactivate / End / Remove - TBD

7. Any other -

Collections/Taxonomy logic:

In Shopify collections are the equivalent of "Store categories" for other marketplaces

Documentation: CustomCollection

Download Collections - GET custom collections
~~Create Collection - CustomCollectionCreate - in this section of do documentation search for the method "Create a custom collection with an image, which will be uploaded to Shopify"~~
~~Update Collection - Update Collection - As Shopify doesn't offer an operation to update the title of a given collection we will have to delete it and create a new one.~~
Add Product to collection - Add Product to Collection - this call should be used when we are listing or updating a product.

We will start with first developing the "Add product to Collection".

product_id - ChannelItemID
collection_id - StoreCategoryID

After this one is ready we do "GET Collections"

Example with all fields needed

POST /admin/custom_collections.json
{
  "custom_collection": {
    "title": "Macbooks",
    "metafields": [
      {
        "key": "new",
        "value": "newvalue",
        "value_type": "string",
        "namespace": "global"
      }
     "image": {
        "src": "http://example.com/rails_logo.gif",
        "alt": "Rails Logo"
      }
    ]
  }
}

question 1: Can we connect "collection" to "navigation" over API?

Answer: No

question 2: Do we keep 1 taxonomy per WAP instance no matter of how many Shopify accounts have been integrated?

Answer: Yes we keep only 1 taxonomy per WAP instance.

question 3: Do collections with the same name have different ID for each separate Shopify website?

Answer: Yes, they do.

question 4: How do we handle multiple ID's per "collection name" in one WAP instance?

Answer: Most probably using prefixes for each Shopify account integrated to that system.

As this is most probably going to require change in the DB - Former user (Deleted), Nikolay Ivanov (Unlicensed), @Ralitsa Romanova, can you please take a look and advise how to handle this.

To handle all of the requirements, after all questions have been answered, we would need to develop an external application which will be used to create collections and eventually if possible to connect the collections to navigation.

After everything about "Create Collection" is cleared we can continue with "Update Collection". As Shopify doesn't provide an operation to change the "title" of the collection we will need to do 2 steps:

~~1. Delete the collection~~

~~2. Create it from scratch~~

~~As this would generate a whole new ID we will advise the users to be careful how they use this option and to know that they would have to change their ID's on the products as well.~~

~~After it's decided how we would handle the problems described above we can then use this solution to download the "Collections" and store them in the specified way.~~

When we start working on the collections we need to look into SEO updates the documentation can be found HERE

We need to be creating and updating only fields:

metafields_global_title_tag
metafields_global_description_tag

You can name them Meta Title and Meta Description

3. Product Delete

In Shopify we are able to delete products and we want to be able to do that.

Orders flows - specifics

1. Get orders -

Download of all new orders since the last time the cron ran. In order to do that use the field w **for filtering when you do GetOrders.**

Order item logic:

Unique lines will be created for each quantity for each SKU in the order.

For each order_item_line there is going to be a Status either "Shipped", "Unshipped" or "Cancel".

For each order_item there is going to be a Status either "Shipped", "Unshipped", "Partially Shipped" or "Cancel"

IF all order_item_lines are shipped the whole order_item will have status "Shipped"
IF all order_item_lines are "Unshipped" the whole order_item will have status "Unshipped"
IF all but one order_item_line is shipped (only one line has status "Unshipped") we will set the whole order_item with status "Partially Shipped". In that case there are no order_item_lines with status "Cancel"
IF there is at least one order_item_line with status "Shipped" and all others are with status "Cancel" then order_item status will be "Partially Shipped". In that case there are no order_item_lines with status "Unshipped"
IF all order_item_lines are with status "Cancel" then the whole order_item gets status "Cancel"
IF there is at least 1 order_item_line with status "Shipped", at least 1 order_item_line with status "Unshipped" and at least 1 order_item_line with status "Cancel" the whole order_item will get status "Partially Shipped"

Get Modified Orders - Download and update all orders that have modification in them.

Use the same fields that are used for Get orders.

2. Ship orders - Ship orders that are marked in WAP systems as "ready_to_ship"

Fulfill Order logic:

In order to fulfill an order you need to follow the steps below:

а. Do Fulfillment call (post fulfillment)

Please find the documentation HERE

First case scenario to be used only if "Shipping Tracking URL" is available in WAP systems.

Please find in the documentation the case described as: Fulfill an order using only a tracking number and a custom tracking URL (respects tracking URL but attempts to generate tracking company if number matches recognizable pattern)

"location_id" - for this one use the location ID which you are using for the stock updates. "tracking_number" - for this one use Shipping Track Number "tracking_url" - for this one use the Shipping Tracking URL "line_items" - for this one use all Item Order Line ID's from order_item for the specified order

Second case scenario to be used only if "Shipping Tracking URL" is not available in WAP systems.

Please find in the documentation the case described as: Fulfill an order using a non-supported tracking company without a tracking URL (generates best guess URL if number matches recognizable pattern)

"location_id" - for this one use the location ID which you are using for the stock updates. "tracking_number" - for this one use Shipping Track Number "tracking_company" - for this one use Shipping Carrier "line_items" - for this one use all Item Order Line ID's from order_item for the specified order

~~b. Do fulfillment state call~~

~~Initially we start with Full order fulfillment so you need to use "CompleteFulfillment". In the future we might decide to develop partial fulfillment as well.~~

c. ~~Do FulfillmentEvent call - If this step is NOT MANDATORY and the order gets marked as shipped when we create fulfillment then this step becomes obsolete.~~

~~Please use FulfillemtEventCreate using status: "in_transit". When you receive a positive response to that call mark the order as "delivered" in WAP systems.~~

3. Cancel orders -

4. Refund orders -

Please find the documentation HERE

Shopify differentiates between full item refund, partial item refund, full shipping refund and partial shipping refund so we need to be able to do all of them.

First in order to complete a refund we need to use the calculate endpoint /admin/orders/450789469/refunds/calculate.json and after it is successful we can continue with the actual refund endpoint /admin/orders/450789469/refunds.json

The logic is similar to other marketplaces:

When we create the refund row in the system we need to be able to select the refund type (full, item, shipping) and then send it to Shopify.

On the first call it's possible to receive an error that the calculation is not correct it will have information in the response what is to be changed. We need to write it in the error field so the user will be aware what has gone wrong.

As we don't want Shopify to recalculate the stock we need to be sending restock_type = no_restock. !!! This might change !!!

As we did with the notifications for shipping update ("notify": true,) we need the same functionality for the notifications for refunds - a flag on account level that can be either disabled or enabled to use the feature or not.

Store on order_item_line status refunded if the refund has been completed. On order_item if the refund is not for the whole order_item just for some of it's quantity write partial refund as status.

5. Any other -

Other - specifics

Development phases:

Phase one:

Phase two (sorted by priority):

Tie product/variation to collection

SEO update

Download collections.

Get orders update:

Write down payment details. This will be developed with Refunds.

Refund

Listing requirements:

Weight is required - added as an Item Specific and has to be with the name "weight" with small "w"

ALL Item Specifics different from "weight" will be sent to Shopify as "tags" all values with comma separator (e.g. blue, carbon fibre, etc...)

price

quantity

product category - is sent to Shopify as "Product Type"

description

Listing status: must have the value "Inactive"

Product status: must have the value "Awaiting creation"

Currently working functionalities:

List product
Update stock
Update price
Download orders
Update product - in progress
Fulfill order - in progress
Tie "Collections" to products
Download "Collections"

Functionalities to be developed:

Refunds

Future development:

Design template specifics:

In product account there is a sub-table called "item account Shopify" it contains the following fields:

Field names:

date
varaint_id
product_image
image1
image2
image3
supplier_description

Field "Tag":

N/A
N/A
N/A
{{image1}}
{{image2}}
{{image3}}
{{supplier_description}}

Outstanding questions

Handling product images

Is this article helpful?

0 0 0