[Delivery] Proposed approach for implementing delivery services

[mochacr0]

Overview

Shipping is crucial to the e-commerce process, beginning when an order is placed and continuing through all steps required to deliver the package to the customer.

The shipping process starts when the user initiates checkout. At this point, they can select their preferred delivery provider, service type, and receive delivery time and fee estimates.

Once the order is confirmed, the shop owner prepares the shipment, including packaging the item, creating a shipping request, and scheduling a pickup time for the carrier. The carrier then manages the fulfillment process to deliver the package.

Throughout this journey, both the buyer and the shop owner can track the package status using a tracking number provided by the carrier.

YAS Delivery Idea

This section outlines the general approach for implementing delivery services into YAS. Since this is still a concept, further discussion is needed to finalize the solution and workflow.

Delivery Providers & Services

We plan to support multiple shipment providers (e.g., FedEx, UPS). Each provider offers a unique list of service types, each with varying rates and delivery times.

During checkout, the system retrieves all available delivery service types from enabled providers that can accommodate the current order details (buyer address, items to ship). Buyers will then select their preferred service type for the order.

Order & Shipment Packages

An order may consist of multiple shipment packages. This is necessary due to our support for multi-warehouse functionality, where products may be located in different warehouses and pickup locations. Since we cannot create a single package for items from various pickup locations, multiple packages will be created, one for each warehouse storing the products.

To illustrate how our system decides on package creation for an order, consider the following stock availability and order scenarios:

	Samsung	Iphone
Warehouse A	10	5
Warehouse B	5	20
Total	15	25

When a user wants to place an order containing both Samsung and iPhone with different quantities, the system processes it as follows:

Scenario 1: Samsung x1, iPhone x1

Since both products are available in both warehouses, the system can select either Warehouse A or B based on proximity to the buyer. However, estimating the distance may be complex for now. We can use a simpler method to choose the warehouse by sorting the names in alphabetical order, for example.

• Package 1 (Warehouse A): Samsung x1, Iphone x1

Scenario 2: Samsung x6, iPhone x6

In this case, only Warehouse A has enough stock for Samsung, while Warehouse B has sufficient stock for iPhone. Therefore, the shop owner must create two different packages:

• Package 1 (Warehouse A): Samsung x6
• Package 2 (Warehouse B): iPhone x6

Scenario 3: Samsung x11, iPhone x21

Here, the ordered quantities exceed the available stock in each warehouse, but the total is still manageable. Consequently, two packages must be created:

• Package 1 (Warehouse A): Samsung x10, iPhone x5
• Package 2 (Warehouse B): Samsung x1, iPhone x16

In this scenario, we prioritize allocation from Warehouse A first because its name comes first alphabetically.

This package-splitting logic is also applied when estimating delivery times and fees to provide accurate information to customers.

Arrange a Shipment

Arranging a shipment occurs after the buyer places an order and the shop owner accepts it. At this stage, shop owners must create a shipment package request for the buyer's chosen provider. The following actions can be performed:

• Choose Package to Ship: If the order consists of multiple packages, the shop owner selects the package to be shipped.

• Choose Pickup Type:
  • Drop-off at Provider Service Location: In this option, shop owners take the package to the provider's drop-off location. This process occurs outside the system. Once completed, they must enter the package information (e.g., tracking number, expected delivery time) into the system.
  • Schedule a Pickup Request: Shop owners can schedule a date and time for the shipment provider to pick up the package. In this case, the package information updates automatically after the request is submitted, eliminating the need for manual entry.

• Choose Printing Label Options: Each package requires a label, which should be printed and affixed to the package. Shop owners can customize settings like size and format.

• Confirm Arranging the Shipment: After all selections are made, shop owners confirm the arrangement of the shipment.

Package Status Updating & Tracking

Once the shipment package is arranged and picked up, its status is continuously updated by the delivery providers via webhooks. Each time there is a change in the package's status—such as being picked up, moved to storage, out for delivery, or delivered—providers send update events to our system through pre-configured endpoints. Our system is responsible for receiving these updates and reflecting the accurate status of the package.

Additionally, each package is assigned a unique tracking number, allowing us to retrieve the latest status and details from the provider's website.

Note: Webhooks are only available for deployed and public environments. They are not sent in development environments.

Shipping Provider API Specifications

FedEx

1. Get Rates (Delivery Times and Fees)
2. Create Shipment
3. Cancel Shipment
4. Get Pickup Rates
5. Schedule Pickup
6. Cancel Pickup
7. Tracking API

Get Rates (Delivery Times and Fees)

Retrieves available delivery services, estimated delivery times, and associated fees based on shipment details such as addresses, package weight, and pickup type.

Required Information:

• Shipper and recipient address details (postal code, country code).
• Pickup type, hard-coded as "USE_SCHEDULED_PICKUP" for simplicity.
• Items to ship:
  • Weight (required)
  • Optional weight unit.
• rateRequestType (type of rate request).
• Packaging type, hard-coded as "YOUR_PACKAGING" (indicates that the shop owner is responsible for packaging).

Response Includes:

• List of possible services, with each service providing:
  • Service description (service code and name)
  • Commit date
  • Delivery fee and tax
  • Delivery date

---

Create Shipment

Initiates a shipment request.

Required Information:

• Account number.
• Sender address and contact details, including country code and state/province code.
• Recipient address and contact information.
• Items to ship (weight is required).
• Packaging type, defaults to "YOUR_PACKAGING".
• Pickup type (Dropoff or Pickup).
• Label printing options (format, size).
• Service type.
• Suitable shipping company codes.
• Ship date, assumed to be the expected pickup date.

Response Includes:

• Tracking number
• Total fee and taxes
• Delivery and commit dates
• Bar code
• Label (Base64-encoded)

---

Cancel Shipment

Cancels an existing shipment request.

Required Information:

• Shipment tracking number.

Response Includes:

• Status of the cancellation.
• Status of deletion from history.

---

Tracking API

Provides the latest status and history of a shipment

Required Information:

• Tracking number from the created shipment.

Response Includes:

• Latest status (status and timestamp).
• Status history.

---

Get Pickup Rates (Optional)

Retrieves available pickup rates.

Required Information:

• Pickup address (postal code and country code).
• Pickup type: SAME_DAY, FUTURE_DAY, or both.
• Preferred carriers.
• Pickup date (includes date and time).

Response Includes:

• List of possible pickup rates, detailing available combinations of date, time, and carrier code.

---

Schedule Pickup (Optional)

Schedules a package pickup. This API works in conjunction with the Create Shipment API, as after a shipment is created, shippers can utilize this API to schedule the pickup of their packages, ensuring that their items are picked up at the desired time and location. Note that the pickup request is separate from the create shipment request, as a single pickup may collect multiple shipment packages at one time.

Required Information:

• Pickup location.
• Pickup date and time.
• Carrier code.

Response Includes:

• Pickup confirmation code (used for canceling the pickup).
• Notification message explaining the pickup confirmation.

---

Cancel Pickup (Optional)

Cancels a previously scheduled pickup.

Required Information:

• Pickup confirmation code.
• Date of the pickup request.

Response Includes:

• Message detailing the result of the cancellation.

---

Notes

• For international shipping, weight must be specified in pounds (LB).
• The Tracking API currently returns mock data from 2023, regardless of the input provided.
• Creating international shipments is currently not allowed. It's unclear whether this is a limitation of the sandbox environment or due to missing information in the request. Further testing is needed.

[duylv27]

Testing FedEx API

Rates - Transit Times (estimate fee, delivery date) & Shipment APIs (create shipment)

Make sure request & response consistent (estimated fee, delivery date). Perform some tests on get rates and create shipments APIs to identify any fields in request that may lead to inconsistencies between these two APIs.

Assume that, these 2 APIs require certain fields to be identical for consistency.

• Request:
  • Dynamic fields: fields that could impact to shipment information.
    • Address: recipient, shipper.
    • Contact: recipient, shipper.
    • Residential: if recipient addresses in residential area, if yes, will have external called DELIVERY_AREA (charge only domestic delivery).
    • Product Weight (LB, KG unit). (currently cannot use KG)
    • Pickup date: D+1.
    • Service type: Available service type depend on origin and destination location. There are some combinations don't have any services.
      • STANDART_OVERNIGHT: deliver inside US.
      • INTERNATIONAL_FIRST: international delivery, which will charge more fees (taxes, duties, etc.), will have some note see deliveryMessages. ...
    • Ship Date: if shipDateStamp is saturday, will have external fee called SATURDAY_PICKUP.
    • shipmentSpecialServices: SATURDAY_DELIVERY, SATURDAY_PICKUP. ...
  • Static field: fields that are specific for our application (consider configured values).
    • pickupType: USE_SCHEDULED_PICKUP.
    • packagingType: YOUR_PACKAGING (customer-self packaging)
    • shippingChargesPayment.paymentType: SENDER
• Response: important fields that are used to by our application to show to customer, calculate total order amount, etc.
  • Total shipment fee: list out all needed fields.
  • External shipment fees (optional): check if there is any fields that can impact to final total fee.
  • Delivery Date: check object operationalDetail.
  • Delivery on weekend: return based on shipDateStamp.
  • Tracking number: _

  • x-customer-transaction-id: our internal transaction id. ...

    Test Service Type & Address combination

    1. Rate & Transit Time: Test service type vs address combination. 2. Create Shipment: After Checking Rate: check if we can create shipment as checking rate request.