Shopify as ERP Order Management Technical Scope

We will have reverse flow when we are treating Shopify as an ERP system and we will be creating the orders in Shopify once we download them from the Marketplaces in Hemi.

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Create Order

API Call: POST /admin/api/2022-01/orders.json

API Docs: https://shopify.dev/api/admin-rest/2022-01/resources/order#post-orders

Also depend on the setup in Shopify Connector > Send Order Confirmation and Shopify Connector > Send Shipping Confirmation we will need to include additional body parameters

We create order in Shopify when we have:

<v2.7> Orders > Order Status (orders.tool_status) IN (Shipped, Ready For Shipping) however we want to have additional option in the Shopify Connector and specify on what status we would like to create the orders.either “Ready For Shipping”, “Shipped” or both.</v2.7>

Order > Connector Order ID = ““ OR Order Item > Connector Order ID = ““ Order Item > Connector Exported = No Order > Connector Error = ““

Example Call: Add as body

{
   "order":{
      "checkout_id":32535203021015,
      "source_identifier":205-64548-6541,
       "inventory_behaviour": "decrement_obeying_policy",
      "created_at":"2022-03-17T09:18:44+02:00",
      "currency":"GBP",
      "send_receipt" : "true",
      "send_fulfillment_receipt " : "true",
      "phone":"0896352803",
      "email":"jane@example.com",
      "note":"HemiID",
      "tags":"",
      "taxes_included":false,
      "financial_status":"paid",
      "fulfillment_status":"fulfilled",
      "total_tax":"2.75",
      "note_attributes":[
{
"name": "Amazon Order ID",
"value": "#206-2904062-8262744"
},
{
"name": "Fulfillment Channel",
"value": "Merchant"
},
{
"name": "Sales Channel",
"value": "Amazon.co.uk"
},
{
"name": "E-mail",
"value": "sh2ttrq7xwtkq9g@marketplace.amazon.co.uk"
},
{
"name": "Earliest Ship Date",
"value": "Tue, Apr 19, 2022 2:00 AM"
},
{
"name": "Latest Ship Date",
"value": "Wed, Apr 20, 2022 1:59 AM"
},
{
"name": "Earliest Delivery Date",
"value": "Wed, Apr 20, 2022 2:00 AM"
},
{
"name": "Latest Delivery Date",
"value": "Thu, Apr 21, 2022 1:59 AM"
},
{
"name": "Phone",
"value": "07970775833"
}
],
      "line_items":[
         {
            "variant_id":40016814276662,
            "quantity":1,
            "price":"10",
            "fulfillment_service":"manual",
            "variant_inventory_management":"shopify",
            "properties":[
{
"name": "ASIN",
"value": "B00RD00VRW"
},
{
"name": "Deemed Reseller Category",
"value": "GB_VOEC"
}
],
            "tax_lines":[
               {
                  "price":2,
                  "rate":0.2,
                  "title":"Item VAT"
               }
            ]
         }
      ],
      "customer":{
         "first_name":"Paul",
         "last_name":"Norman",
         "email":"simona@abv.bg"
      },
      "billing_address":{
         "first_name":"John",
         "last_name":"Smith",
         "address1":"123 Fake Street",
          "address2":"123 Fake Street",
         "phone":"555-555-5555",
         "city":"Fakecity",
         "province":"Ontario",
         "country":"Canada",
         "company": "Canada",
         "zip":"K2P 1L4"
      },
      "shipping_address":{
         "first_name":"Jane",
         "last_name":"Smith",
         "address1":"123 Fake Street",
         "address2":"123 Fake Street",
         "phone":"777-777-7777",
         "city":"Fakecity",
         "province":"Ontario",
         "country":"Canada",
         "zip":"K2P 1L4"
      },
      "fulfillments":[
         {
            "tracking_company":"test",
            "tracking_number":"test2",
            "tracking_url":"www.test.bg",
            "location_id":61653844022
         }
      ],
      "shipping_lines":[
         {
            "code":"До Офис На Спиди",
            "title":"До Офис На Спиди",
            "price":"4.50",
            "source":"shopify",
            "tax_lines":[
               {
                  "price":"0.75",
                  "rate":0.2,
                  "title":"Shipping VAT"
               }
            ]
         }
           ],
 "transactions":[
         {
            "kind":"capture",
            "status":"success",
            "currency":"GBP",
            "gateway":"manual",
            "amount":94.92
         }
      ],
      "discount_codes":[
         {
            "code":"FAKE30",
            "amount":"9.00",
            "type":"percentage"
         }
      ]
   }
}

Call Mapping: Please note everything which is N/A can be excluded from the paylaod. If any of the mapped fields is also empty we do not include it in the payload. For example if we dont have Order Payment> Transaction ID we do not include checkout_id in the payload! However if the payment row is missing we need to return and error in connector error

If the Order Payment> Transaction ID is missing we will be using Order >Marketplace Order ID However if the payment row is missing we need to return and error in connector error If Account Shopify Connector > Skip order if no transaction ID = Yes then the following case: we skip the order and do not set an error in connector error | | | source_identifier | | | | | Order >Marketplace Order ID | | | | created_at | | | | | Order > Order Created Time | date format - 2022-03-21T15:31:06+02:00 | | | inventory_behaviour | | | | | Shopify Connector > Inventory Behaviour | | | | currency | | | | | Order > Order Currency | If Active Currency Conversion = Yes we use the Shopify Connector > Shopify Currency | | | send_fulfillment_receipt | | | | | | If Shopify Connector >Send Shipping Confirmation = true | | | send_receipt | | | | | | If Shopify Connector > Send Order Confirmation = true | | | phone | | | | | N/A | Do not send in this node, just in ‘shipping’ and ‘billing’. | | | email | | | | | Order > Order > Buyer mail | Trim leading white spaces if any <v3.1>Based on the flag in Shopify Connector > Send Customer Email (under settings tab) we will push the email</v3.1> | | | note | | | | | Order > ID | | | | tags | | | | | <v2.8>Account Shopify Connector > Order Tag</v2.8> | New text field which will export a tag with the order <2.9>If empty we do not include in the payload</2.9><v2.8> | | | taxes_included | | | | | | If Account Shopify Connector > Create Order Tax Excluded = No we push “true“ If Account Shopify Connector > Create Order Tax Excluded = Yes we push “false“ | | | financial_status | | | | | | We need to map paid -Order Payment > Status = Completed null - Order Payment > Status != Completed | | | transactions | | | | | | | | | | kind | | | | | Hardcoded as “capture“ | | | | status | | | | | Hardcoded as “success“ | | | | currency | | | | Orders > Оrder Currency | If Active Currency Conversion = Yes we use the currency from the Shopify Connector > Shopify Currency | | | | gateway | | | | N/A | <v2.6>We want to unmap this field and remove it from the payload</2.6> | | | | amount | | | | Orders > Оrder Тotal Аmount | | | | fulfillment_status | | | How far along an order is in terms line items fulfilled. Valid values: null, fulfilled, partial, and not_eligible | | | We need to map fulfilled - Orders> Order Status = Shipped null - Orders> Order Status = Ready For Shipping | | | total_tax | | | | | Order > Total VAT Orders > Total Tax Amount | If we have the Total Tax Amount populated we push the all tax fields: Orders > Total Tax Amount Order Item > Item Tax Price Order Item > Tax Percent Orders > Shipping Sales Tax By default we use our VAT fields If Active Currency Conversion = Yes we convert according to the selected currency | | | note_attributes | | | | | Orders > Marketplace Order ID Orders> Marketplace Fulfillment Channel Orders Amazon > Latest Ship Date Orders > Buyer User ID Orders > Selling Manager SalesRecordNumber Orders > Shipping Service | We include only the fields which are not empty so if we have Amazon orders we will have Fulfillment Channel and Latest Ship Date but if we have eBay we will have Sales Rec Num and Buyer User ID.

For the name we will be using our field label and for the value we are pushing our values. | | | | | | name | | | We specify the field label | | | | | | value | | | We specify the field value | | | line_items | | | | | | | | | | variant_id | | | | Item Shopify > Variant ID | We need to use the Order Item > SKU and map it with Item > SKU in order to get the correct Inventory Item ID | | | | quantity | | | | Order Item > Item Quantity | | | | | price | | | | Order Item > Item Trans Price | If Active Currency Conversion = Yes we convert according to the selected currency | | | | fulfillment_service | | | | | hardcode as “manual" | | | | variant_inventory_management | | | | | hardcode as “shopify" | | | | properties | | | | | For the name we will be using our field label and for the value we are pushing our values. | | | | | name | | | | We specify the field label e.g “Channel Item ID“ | | | | | value | | | Order Item > Channel Item ID | We specify the label value e.g “13123123“ | | | | tax_lines | | | | | | | | | | price | | | Order Item > Vat Item Price Order Item > Item Tax Price | If we have the Total Tax Amount populated we push the all tax fields: Orders > Total Tax Amount Order Item > Item Tax Price Order Item > Tax Percent Orders > Shipping Sales Tax We need to multiply the tax by the item quantity when pushing to Shopify By default we use our VAT fields If Active Currency Conversion = Yes we convert according to the selected currency | | | | | rate | | | Order Item > Vat Percent Order Item > Tax Percent | we will need to divide our percentage amount by 100 and push it like “0.20“ If we have the Total Tax Amount populated we push the all tax fields: Orders > Total Tax Amount Order Item > Item Tax Price Order Item > Tax Percent Orders > Shipping Sales Tax By default we use our VAT fields

If Order Item > Tax Percent is missing we need to calculate it internally (Order Item > Item Tax Price / Order Item > Item Price)

We need to round it at the 2nd decimal | | | | | title | | | | hardcode as “Item VAT" | | | customer | | | | | | | | | | first_name | | | | Order > Shipping Buyer Name | We need only the first name and we get everything before the first space character

Trim leading white spaces if any | | | | last_name | | | | Order > Shipping Buyer Name | We need only the last name and we get everything after the last space character

Trim leading white spaces if any | | | | email | | | | Order > Buyer Email | Trim leading white spaces if any <v2.5>Based on the flag in Shopify Connector > Send Customer Email (under settings tab) we will push the email</v2.5> | | | billing_address | | | | | | | | | | first_name | | | | Order > Billing Name | We need only the first name and we get everything before the first space character

Trim leading white spaces if any | | | | address1 | | | | Order > Billing street 1 | Trim leading white spaces if any | | | | phone | | | | Order > Billing Phone | Trim everything except for the numbers | | | | city | | | | Order > Billing City Name | Trim leading white spaces if any | | | | zip | | | | Order > Billing Postal Code | | | | | province | | | | Order > Billing State Province | Trim leading white spaces if any | | | | country | | | | Order > Billing Country Name | Trim leading white spaces if any | | | | company | | | | Order > Company Name OR Account > Name | Trim leading white spaces if any

If we have activated in Account Shopify Connector > Channel as company name we will sent Account > Name as company. | | | | last_name | | | | Order > Billing Name | We need only the last name and we get everything after the last space character Trim leading white spaces if any | | | | address2 | | | | Order > Billing street 2 | Trim leading white spaces if any | | | | name | | | | Order > Billing Name | Trim leading white spaces if any | | | | country_code | | | | Order > Billing Country Code | | | | shipping_address | | | | | | | | | | first_name | | | | Order > Shipping Buyer Name | We need only the first name and we get everything before the first space character

Trim leading white spaces if any | | | | address1 | | | | Order > Shipping street 1 | Trim leading white spaces if any | | | | phone | | | | Order > Shipping Phone | Trim everything except for the numbers | | | | city | | | | Order > Shipping City | Trim leading white spaces if any | | | | zip | | | | Order > Shipping Postal Code | | | | | province | | | | Order > Shipping State Province | Trim leading white spaces if any | | | | country | | | | Order > Shipping Country Name | Trim leading white spaces if any | | | | last_name | | | | Order > Shipping Buyer Name | We need only the last name and we get everything after the last space character Trim leading white spaces if any | | | | address2 | | | | Order > Shipping street 2 | Concatenate ‘Orders Ebay > IOSS' and 'Orders > Shipping Street 2’. Trim leading white spaces if any | | | | name | | | | Order > Shipping Buyer Name | Trim leading white spaces if any | | | | country_code | | | | Order > Shipping Country Code | | | | fulfillments | | | | | | If the order is “shipped” and the shipments are with status “completed” or “warning“ and we have the shipping details we push them as follows;

Also if we have Order Items with different locations we need to group the SKUs per location and push them as two separate fulfillment nodes. e.g. "order":{ "id": 4743616168183, "fulfillments":[ {"id": 4231381680375, "admin_graphql_api_id": "gid://shopify/Fulfillment/4231381680375", "created_at": "2022-04-18T11:02:19+03:00",…},

{"id": 4231381975287, "admin_graphql_api_id": "gid://shopify/Fulfillment/4231381975287", "created_at": "2022-04-18T11:03:10+03:00",…} ] } | | | | tracking_company | | | | Order > Courier | | | | | tracking_number | | | | Order > Shipping Track Number | | | | | tracking_url | | | | Order > Shipping Track URL | | | | | location_id | | | | Shopify Connector Locations > External ID | We need to map the SKU Location Id | | | shipping_lines | | | | | | | | | | code | | | | Account > Marketplace + Order > Shipping Service OR Account Shopify Connector > Order Shipping Method | <v3.2> We want to introduce a new input field Order Shipping Method (default value empty) which allows us to send custom Shipping Method for each Shopify order. So if we have added value in Account Shopify Connector > Order Shipping Method we want to pick it with priority. If Account Shopify Connector > Order Shipping Method is empty </3.2>we need to concatenate Account > Marketplace plus the actual service from the order. If the Shipping Service is missing from the order we push only Account > Marketplace | | | | title | | | | Account > Marketplace + Order > Shipping Service OR Account Shopify Connector > Order Shipping Method | <v3.2> We want to introduce a new input field Order Shipping Method (default value empty) which allows us to send custom Shipping Method for each Shopify order. So if we have added value in Account Shopify Connector > Order Shipping Method we want to pick it with priority. If Account Shopify Connector > Order Shipping Method is empty </3.2>we need to concatenate Account > Marketplace plus the actual service from the order. If the Shipping Service is missing from the order we push only Account > Marketplace | | | | price | | | | Order > Shipping Service Cost | If Active Currency Conversion = Yes we convert according to the selected currency | | | | source | | | | | Hardcode as 'shopify' | | | | tax_lines | | | | | | | | | | price | | | SUM(Order Item >Vat Shipping Cost Value) Orders > Shipping Sales Tax | The total Shipping Cost VAT

If we have the Total Tax Amount populated we push the all tax fields: Orders > Total Tax Amount Order Item > Item Tax Price Order Item > Tax Percent Orders > Shipping Sales Tax By default we use our VAT fields If Active Currency Conversion = Yes we convert according to the selected currency | | | | | rate | | | Order Item > Vat Percent Order Item > Tax Percent | If we have different VAT rates we pick the highest rate from the order items. we will need to divide our percentage amount by 100 and push it like “0.20“ If we have the Total Tax Amount populated we push the all tax fields: Orders > Total Tax Amount Order Item > Item Tax Price Order Item > Tax Percent Orders > Shipping Sales Tax By default we use our VAT fields

If Order Item > Tax Percent is missing we need to calculate it internally (Order Item > Item Tax Price / Order Item > Item Price)

We need to round it at the 2nd decimal | | | | | title | | | | Hardcoded as “Shipping VAT“ | | | discount_codes | | | | | | | | | | code | | | | N/A | | | | | amount | | | | N/A | | | | | type | | | | N/A | |

Example Response:

HTTP/1.1 201 Created
{
  "order": {
    "id": 1073459964,
    "admin_graphql_api_id": "gid://shopify/Order/1073459964",
    "app_id": 755357713,
    "browser_ip": null,
    "buyer_accepts_marketing": false,
    "cancel_reason": null,
    "cancelled_at": null,
    "cart_token": null,
    "checkout_id": null,
    "checkout_token": null,
    "client_details": null,
    "closed_at": null,
    "confirmed": true,
    "contact_email": null,
    "created_at": "2022-03-08T11:10:23-05:00",
    "currency": "USD",
    "current_subtotal_price": "199.00",
    "current_subtotal_price_set": {
      "shop_money": {
        "amount": "199.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "199.00",
        "currency_code": "USD"
      }
    },
    "current_total_discounts": "0.00",
    "current_total_discounts_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "USD"
      }
    },
    "current_total_duties_set": null,
    "current_total_price": "199.00",
    "current_total_price_set": {
      "shop_money": {
        "amount": "199.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "199.00",
        "currency_code": "USD"
      }
    },
    "current_total_tax": "0.00",
    "current_total_tax_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "USD"
      }
    },
    "customer_locale": null,
    "device_id": null,
    "discount_codes": [],
    "email": "",
    "estimated_taxes": false,
    "financial_status": "paid",
    "fulfillment_status": null,
    "gateway": "",
    "landing_site": null,
    "landing_site_ref": null,
    "location_id": null,
    "name": "#1002",
    "note": null,
    "note_attributes": [],
    "number": 2,
    "order_number": 1002,
    "order_status_url": "https://jsmith.myshopify.com/548380009/orders/e067657ef6c64b9548762b80e56e4b81/authenticate?key=a9a11394626a910e4e3d1fd3ca4fd888",
    "original_total_duties_set": null,
    "payment_gateway_names": [],
    "phone": null,
    "presentment_currency": "USD",
    "processed_at": "2022-03-08T11:10:23-05:00",
    "processing_method": "",
    "reference": null,
    "referring_site": null,
    "source_identifier": null,
    "source_name": "755357713",
    "source_url": null,
    "subtotal_price": "199.00",
    "subtotal_price_set": {
      "shop_money": {
        "amount": "199.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "199.00",
        "currency_code": "USD"
      }
    },
    "tags": "",
    "tax_lines": [],
    "taxes_included": false,
    "test": false,
    "token": "e067657ef6c64b9548762b80e56e4b81",
    "total_discounts": "0.00",
    "total_discounts_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "USD"
      }
    },
    "total_line_items_price": "199.00",
    "total_line_items_price_set": {
      "shop_money": {
        "amount": "199.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "199.00",
        "currency_code": "USD"
      }
    },
    "total_outstanding": "199.00",
    "total_price": "199.00",
    "total_price_set": {
      "shop_money": {
        "amount": "199.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "199.00",
        "currency_code": "USD"
      }
    },
    "total_price_usd": "199.00",
    "total_shipping_price_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "USD"
      }
    },
    "total_tax": "0.00",
    "total_tax_set": {
      "shop_money": {
        "amount": "0.00",
        "currency_code": "USD"
      },
      "presentment_money": {
        "amount": "0.00",
        "currency_code": "USD"
      }
    },
    "total_tip_received": "0.00",
    "total_weight": 0,
    "updated_at": "2022-03-08T11:10:23-05:00",
    "user_id": null,
    "billing_address": null,
    "customer": null,
    "discount_applications": [],
    "fulfillments": [],
    "line_items": [
      {
        "id": 1071823174,
        "admin_graphql_api_id": "gid://shopify/LineItem/1071823174",
        "fulfillable_quantity": 1,
        "fulfillment_service": "shipwire-app",
        "fulfillment_status": null,
        "gift_card": false,
        "grams": 567,
        "name": "IPod Touch 8GB - Black",
        "price": "199.00",
        "price_set": {
          "shop_money": {
            "amount": "199.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "199.00",
            "currency_code": "USD"
          }
        },
        "product_exists": true,
        "product_id": 921728736,
        "properties": [],
        "quantity": 1,
        "requires_shipping": true,
        "sku": "IPOD2009BLACK",
        "taxable": true,
        "title": "IPod Touch 8GB",
        "total_discount": "0.00",
        "total_discount_set": {
          "shop_money": {
            "amount": "0.00",
            "currency_code": "USD"
          },
          "presentment_money": {
            "amount": "0.00",
            "currency_code": "USD"
          }
        },
        "variant_id": 447654529,
        "variant_inventory_management": "shipwire-app",
        "variant_title": "Black",
        "vendor": "Apple",
        "tax_lines": [],
        "duties": [],
        "discount_allocations": []
      }
    ],"transactions":[
         {
            "kind":"capture",
            "status":"success",
            "currency":"GBP",
            "gateway":"manual",
            "amount":94.92
         }
      ],
    "payment_details": null,
    "refunds": [],
    "shipping_address": null,
    "shipping_lines": []
  }
}

Response Mapping:

After successful order creation we will need to update also Order Item > Connector Exported field = Yes If we receive an error during the creation we need to store the error in Order > Connector Error with the relevant error message

<v3.0>If we have bundles we want to include additional option for the bundles in order to control if we would like to export bundle, components or both .

The best way to do this is to add additional dropdown field into Shopify Connector under Order status for export field.

The new field should be called “Order Items for Export” which is required and should have 3 options:

Bundle

Components (Default Value) Both

Based on the selection we would like to select only Bundle products when exporting an order, only component products or all order items.</v3.0>

Create Order with currency conversion

Depends on the selling channels we may need to convert the order amounts when we are creating the order in Shopify. This is required because Shopify can be GBP based however the client is selling in EUR marketplaces. In order to implement this correctly we will need to do currency conversion. The Shopify Store currency will be set in Shopify Connector > Shopify Currency this way we will know to what currency we will need to convert (At the moment the only supported currency is GBP). If we would like to active the actual currency conversion logic we will need to activate Account Shopify Connector > Active Currency Conversion which is per account, this way we can decide for which accounts we would like to convert. Please note if this is activated we will also export the Shopify Connector > Shopify Currency in the payload as currency. The Channel currency is set in Account > Exchange Rate Calculator Currency now we have and from what currency we will need to convert. The actual currency rates will be obtained from Hmrc Rates table from where we will have to pick the most up to date rate for the Shopify Connector > Shopify Currency in order to convert the amounts into the Shopify Currency. Please note Hmrc Rates is updated every month and we will have separate record of the currency for each month that's why it is imported to get the most up to date record of the currency. Once we successfully convert and create the order in Shopify we will need to store the Rate which has been used in Order Payment Shopify > Currency Rate. This way if we receive any refund afterwards we will convert them back correctly. Please note if there are no records in Hmrc Rates table we return an error in Orders > Connector Error

Get Shipments

API Call: GET/admin/api/2022-01/orders.json

API Docs: https://shopify.dev/api/admin-rest/2022-01/resources/order#get-orders?status=any

In order to retrieve the shipping updates from Shopify we will have to constantly checking the updated_at_min date. Basically we will be looking in last_date_run deducting 90 mins from the date_created. If the there is no records for this cron we check for the last 30 days. (format: 2014-04-25T16:15:47-04:00)

Example Call:

-X GET "https://your-development-store.myshopify.com/admin/api/2022-01/orders.json"
-H "X-Shopify-Access-Token: {access_token}"
-P "updated_at_min:date"
-P "fields:id,fulfillments"
-P "limit:250"
-P "status:any"

Example Response:

{
   "order":{
      "id":4742822723831,
      "fulfillments":[
         {
            "id":4230928466167,
            "admin_graphql_api_id":"gid:\/\/shopify\/Fulfillment\/4230928466167",
            "created_at":"2022-04-17T12:16:01+03:00",
            "location_id":68502290679,
            "name":"#1001.1",
            "order_id":4742822723831,
            "origin_address":{

            },
            "receipt":{

            },
            "service":"manual",
            "shipment_status":null,
            "status":"success",
            "tracking_company":"test",
            "tracking_number":"test2",
            "tracking_numbers":[
               "test2"
            ],
            "tracking_url":null,
            "tracking_urls":[

            ],
            "updated_at":"2022-04-17T12:16:01+03:00",
            "line_items":[
               {
                  "id":12139726405879,
                  "admin_graphql_api_id":"gid:\/\/shopify\/LineItem\/12139726405879",
                  "fulfillable_quantity":0,
                  "fulfillment_service":"manual",
                  "fulfillment_status":"fulfilled",
                  "gift_card":false,
                  "grams":0,
                  "name":"Test title for money",
                  "price":"10.00",
                  "price_set":{
                     "shop_money":{
                        "amount":"10.00",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"10.00",
                        "currency_code":"GBP"
                     }
                  },
                  "product_exists":true,
                  "product_id":7588270899447,
                  "properties":[

                  ],
                  "quantity":1,
                  "requires_shipping":true,
                  "sku":"80562211967#TESTSTORESOME",
                  "taxable":true,
                  "title":"Test title for money",
                  "total_discount":"0.00",
                  "total_discount_set":{
                     "shop_money":{
                        "amount":"0.00",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"0.00",
                        "currency_code":"GBP"
                     }
                  },
                  "variant_id":42646500409591,
                  "variant_inventory_management":"shopify",
                  "variant_title":null,
                  "vendor":"Martiegolempich",
                  "tax_lines":[
                     {
                        "channel_liable":null,
                        "price":"2.00",
                        "price_set":{
                           "shop_money":{
                              "amount":"2.00",
                              "currency_code":"GBP"
                           },
                           "presentment_money":{
                              "amount":"2.00",
                              "currency_code":"GBP"
                           }
                        },
                        "rate":0.2,
                        "title":"Item VAT"
                     }
                  ],
                  "duties":[

                  ],
                  "discount_allocations":[
                     {
                        "amount":"0.90",
                        "amount_set":{
                           "shop_money":{
                              "amount":"0.90",
                              "currency_code":"GBP"
                           },
                           "presentment_money":{
                              "amount":"0.90",
                              "currency_code":"GBP"
                           }
                        },
                        "discount_application_index":0
                     }
                  ]
               }
            ]
         }
      ]
   }
}

Response Mapping:

Once we get the shipping details from Shopify and the order status is “Ready For Shipping“ we set Order > Update Shipping Pending = Yes, so we can trigger the shipping update to the relevant MP

Get Refunds

API Call: GET/admin/api/2022-01/orders.json

API Docs: https://shopify.dev/api/admin-rest/2022-01/resources/order#get-orders?status=any

In order to retrieve the refunds from Shopify we will have to constantly checking the updated_at_min date. Basically we will be looking in last_date_run deducting 90 mins from the date_created. If the there is no records for this cron we check for the last 30 days. (format: 2014-04-25T16:15:47-04:00)

When we have "refunds": not empty this mean there is return or cancellation or refund on the order but depends what type we will receive additional information.

Example Call:

-X GET "https://your-development-store.myshopify.com/admin/api/2022-01/orders.json"
-H "X-Shopify-Access-Token: {access_token}"
-P "updated_at_min:date"
-P "fields:id,refunds"
-P "limit:250"

Example Response:

{
   "order":{
      "id":4742822789367,
      "refunds":[
         {
            "id":855911465207,
            "admin_graphql_api_id":"gid:\/\/shopify\/Refund\/855911465207",
            "created_at":"2022-04-17T12:17:01+03:00",
            "note":null,
            "order_id":4742822789367,
            "processed_at":"2022-04-17T12:17:01+03:00",
            "restock":true,
            "total_duties_set":{
               "shop_money":{
                  "amount":"0.00",
                  "currency_code":"GBP"
               },
               "presentment_money":{
                  "amount":"0.00",
                  "currency_code":"GBP"
               }
            },
            "user_id":82310332663,
            "order_adjustments":[
               {
                  "id":204269027575,
                  "amount":"-4.50",
                  "amount_set":{
                     "shop_money":{
                        "amount":"-4.50",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"-4.50",
                        "currency_code":"GBP"
                     }
                  },
                  "kind":"shipping_refund",
                  "order_id":4742822789367,
                  "reason":"Shipping refund",
                  "refund_id":855911465207,
                  "tax_amount":"-0.75",
                  "tax_amount_set":{
                     "shop_money":{
                        "amount":"-0.75",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"-0.75",
                        "currency_code":"GBP"
                     }
                  }
               }
            ],
            "transactions":[

            ],
            "refund_line_items":[
               {
                  "id":410337083639,
                  "line_item_id":12139726471415,
                  "location_id":68502290679,
                  "quantity":1,
                  "restock_type":"return",
                  "subtotal":9.1,
                  "subtotal_set":{
                     "shop_money":{
                        "amount":"9.10",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"9.10",
                        "currency_code":"GBP"
                     }
                  },
                  "total_tax":2.0,
                  "total_tax_set":{
                     "shop_money":{
                        "amount":"2.00",
                        "currency_code":"GBP"
                     },
                     "presentment_money":{
                        "amount":"2.00",
                        "currency_code":"GBP"
                     }
                  },
                  "line_item":{
                     "id":12139726471415,
                     "admin_graphql_api_id":"gid:\/\/shopify\/LineItem\/12139726471415",
                     "fulfillable_quantity":0,
                     "fulfillment_service":"manual",
                     "fulfillment_status":"fulfilled",
                     "gift_card":false,
                     "grams":0,
                     "name":"Test title for money",
                     "price":"10.00",
                     "price_set":{
                        "shop_money":{
                           "amount":"10.00",
                           "currency_code":"GBP"
                        },
                        "presentment_money":{
                           "amount":"10.00",
                           "currency_code":"GBP"
                        }
                     },
                     "product_exists":true,
                     "product_id":7588270899447,
                     "properties":[

                     ],
                     "quantity":1,
                     "requires_shipping":true,
                     "sku":"80562211967#TESTSTORESOME",
                     "taxable":true,
                     "title":"Test title for money",
                     "total_discount":"0.00",
                     "total_discount_set":{
                        "shop_money":{
                           "amount":"0.00",
                           "currency_code":"GBP"
                        },
                        "presentment_money":{
                           "amount":"0.00",
                           "currency_code":"GBP"
                        }
                     },
                     "variant_id":42646500409591,
                     "variant_inventory_management":"shopify",
                     "variant_title":null,
                     "vendor":"Martiegolempich",
                     "tax_lines":[
                        {
                           "channel_liable":null,
                           "price":"2.00",
                           "price_set":{
                              "shop_money":{
                                 "amount":"2.00",
                                 "currency_code":"GBP"
                              },
                              "presentment_money":{
                                 "amount":"2.00",
                                 "currency_code":"GBP"
                              }
                           },
                           "rate":0.2,
                           "title":"Item VAT"
                        }
                     ],
                     "duties":[

                     ],
                     "discount_allocations":[
                        {
                           "amount":"0.90",
                           "amount_set":{
                              "shop_money":{
                                 "amount":"0.90",
                                 "currency_code":"GBP"
                              },
                              "presentment_money":{
                                 "amount":"0.90",
                                 "currency_code":"GBP"
                              }
                           },
                           "discount_application_index":0
                        }
                     ]
                  }
               }
            ],
            "duties":[

            ]
         }
      ]
   }
}

Response Mapping (Please note only the fields which we will need to store are added):

If we have "kind": "shipping_refund" the Order Refund Row > Type = Shipping and the amount will be split proportionately across all items. Here we need to check only for shipping refunds because all item refunds will be included in the refund line items | | | | refund_line_items | | | | | | | | | | | subtotal | | | Y | Order Refund Row > Amount | This price will the price * quantity from the payload If Active Currency Conversion = Yes and Order Payment > Currency Rate are populated we will need to convert the amount. | | | | | line_item | | | | | Here we will need to check of all products are refunded or not and based on this we will know if it is a partial refund or full. If it is full refund we add everything as refund rows. | | | | | | sku | | Y | Order Refund Row > SKU | Please note the line item are always Order Refund Row > Type = Item |

Please note this should create the Order Payment in Hemi with: Order Payment > Type = Refund Order Payment > Status = Pending Order Payment >Process by MP = Yes Order Payment > Refund Type = Full Refund, Partial Refund (depends on the line items )

If Account > Active Currency Conversion is activated and the order is created in Shopify with converted currency and the Order Payment > Currency Rate is populated this means when we are getting the refund we will need to revert back the currency conversion and the store in Hemi the amount in Marketplace currency not in Shopify Currency.