Big Commerce Ship Orders

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)

All validations, triggers and standardizations are as per Order management general requirements

Ship Orders

The purpose of this document is to describe how we ship orders on Big Commerce marketplace

There is a predefined carriers which we can use and we have to introduce carrier mapping. However they are not available for download via API and we need to prepare the enumerations in the database manually.

tracking_carrier_values.csv

Please note we want to send the code and display the name in the UI

All this should be introduced in a new table called “Big Commerce Couriers Mapping“ which we want to be a dependent table of Courier. In “Big Commerce Couriers Mapping“ we want to have all the available enumerations in a dropdown field. We are following the same pattern as standard and the mapping will be first we map the Order Shipment > Courier against Carrier > Name and get the Big Commerce Couriers Mapping > Big Commerce Courier. <v1.3> If NO Courier is provided on the order we want to introduce a default option in Account Big Commerce. If there is no mapping for the provided Courier on the order we want to set an error in Order Error table. </v1.3>

Order Ship API is synchronous process and we receive the response right after the request. Also we will be shipping order per order.

Big Commerce do support partial shipping updates so we want to implement the partial shipping logic.

We want all triggers, status, error handling, etc. to be as per the standard shipping abstraction

API Call: POST https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{order_id}/shipments Doc:https://developer.bigcommerce.com/docs/rest-management/orders/order-shipments#create-order-shipment

Sample Request: POST https://api.bigcommerce.com/stores/oduzegjfvn/v2/orders/100/shipments Body:

{
   "order_address_id":1,
   "tracking_number":"w4se4b6ASFEW4T",
   "tracking_link":"https://www.royalmail.com/track-your-item",
   "tracking_carrier":"2GO",
   "items":[
      {
         "order_product_id":1,
         "quantity":1
      }
   ]
}

Mapping:

OR Courier > Courier Url | No | If we have Order Shipment > Tracking URL we want to pick it with priority otherwise we use Courier > Courier Url as default and if both fields are empty we exclude it from the payload.</v1.2> | | tracking_carrier | | Order Shipment > Courier | Yes | This is the value returned based on the mapping | | items | | | | | | | order_product_id | Product In Order > Item Order Line ID | Yes | The mapping should go through Order Shipment Rows in order to get the correct Product In Order > Item Order Line ID | | | quantity | Order Shipment Rows > Quantity | Yes | |

Sample Response:Status 200 OK

{
    "id": 2,
    "order_id": 102,
    "customer_id": 0,
    "order_address_id": 3,
    "date_created": "Wed, 30 Aug 2023 21:30:46 +0000",
    "tracking_number": "w4se4b6ASFEW4T",
    "merchant_shipping_cost": "0.0000",
    "shipping_method": "Free Shipping",
    "comments": null,
    "shipping_provider": "freeshipping",
    "tracking_carrier": "zto-express",
    "tracking_link": "",
    "billing_address": {
        "first_name": "Богомил",
        "last_name": "Павлов",
        "company": "Бебе-Мама 2019 ООД",
        "street_1": "Гродно 10, test, test, test, test",
        "street_2": "test",
        "city": "София",
        "state": "",
        "zip": "1000",
        "country": "Bulgaria",
        "country_iso2": "BG",
        "phone": "+359896352803",
        "email": "bogomilpavlov@yahoo.com"
    },
    "shipping_address": {
        "first_name": "Богомил",
        "last_name": "Павлов",
        "company": "Бебе-Мама 2019 ООД",
        "street_1": "Гродно 10, test, test, test, test",
        "street_2": "test",
        "city": "София",
        "state": "",
        "zip": "1000",
        "country": "Bulgaria",
        "country_iso2": "BG",
        "phone": "+359896352803",
        "email": "bogomilpavlov@yahoo.com"
    },
    "items": [
        {
            "order_product_id": 3,
            "product_id": 115,
            "quantity": 1
        }
    ]
}

Sample Error Response #1:

{
  "errors": {
    "error": {
      "status": 400,
      "message": {
        "__cdata": "The field 'quantity' is invalid."
      },
      "details": {
        "invalid_reason": "The quantity specified is greater than the quantity of the product that is available to ship.",
        "available_quantity": 0,
        "order_product_id": 1
      }
    }
  }
}

Sample Error Response #2:

{
  "errors": {
    "error": {
      "status": 400,
      "message": {
        "__cdata": "The field 'tracking_carrier' is invalid."
      },
      "details": {
        "invalid_reason": {
          "__cdata": "The provided 'tracking_carrier' value is invalid. Please check valid tracking carrier list or enter empty string ''."
        }
      }
    }
  }
}

Sample Error Response #3:

{
  "errors": {
    "error": {
      "status": 400,
      "message": "The JSON content provided as input is invalid. Please check your JSON syntax before trying again."
    }
  }
}

We want to store the Error > Message as an error in Hemi in Order Error Table.