Shipping Methods Management

Shipping methods management (SMM) refers to the process of delivering products and managing the shipping options that are available to customers. Various tools and features help merchants manage their shipping methods management system, such as shipping calculators, shipping labels, and tracking information. This document covers Ucraft Next back-end API for SMM, which developers may use to get to know the shipping methods management system.

Ucraft Next provides two primary tools and techniques for managing shipping methods management system: Self Pickup and Shipping Profile. Merchants can manually create tools and manage the shipping methods management system from the Shipping & Delivery subsection of the Settings section. The Self Pickup allows customers to pick up their purchases directly from the merchant's physical location. In contrast, the Shipping Profile allows merchants to offer customers different shipping rates and delivery timelines based on their location.

Tech Stack

The Shipping & Delivery subsection comprises two primary tools and techniques for shipping methods management:

• Self Pickup
• Shipping Profile

With Self Pickup, the customer can choose to pick up their order from a specified location rather than having it shipped to them. This is typically used when the customer is located near the merchant's physical location or when they prefer to collect the item themselves.
The Shipping Profile allows the customer to have their order shipped. It also allows shipping the order to a different address, such as a friend's or family member's house as a gift, or to their workplace instead of their home.

The shipping profile selection algorithm works under the hood by retrieving country, state, and zip code information from the customer's shipping address and then comparing it to the available shipping profiles created by merchants. Based on the country and zip code information, the system then retrieves from the GEO API detailed address information, including the zip code, country, state, and city. If the detailed zip code is retrieved from the GEO API, the algorithm shows the relevant shipping profile to the customer.

The following scheme illustrates the above-mentioned information step by step:

In this sample, the zip code belongs to the country (Vatican).

    {
        "zip": "00120",
        "city": "",
        "state_code": "",
        "country_code": "VA"
    }

In this sample, the zip code belongs to the city (Delaware).

    {
        "zip": "19803",
        "city": "New Castle",
        "state_code": "DE",
        "country_code": "US"
    }

The Shipping Profile and the customer's shipping address are interconnected. The customer's shipping address, countries, and states are based on the merchant's shipping profiles countries and states and zip codes. Likewise, the customer's shipping address countries are based on the merchant's Self Pickup location countries.

Based on a Shipping Profile, the available list of countries is shown to the customer, and vice versa. When a customer selects a shipping address and then navigates to see the shipping tools, the system filters those appropriate for that country.
Let's examine the following example: Three shipping profiles have been created for these countries:

1. Armenia-China
2. Armenia-United States
3. China-United States

In this example, three separate shipping profiles have been created for the countries of Armenia, China, and the United States. When a customer enters a shipping address, the system checks the available shipping profiles and displays a list of countries that can be shipped to. For example, if the customer chooses Armenia, the first and second shipping profiles will be shown to them. This allows the customer to pick a shipping destination suitable for the shipping profiles the merchant has set up. Following the selection of a shipping address, the customer is given a choice of available shipping tools. The system then filters out the appropriate shipping types for the specified destination country.

Self Pickup

Customers who select Self Pickup can pick up their goods directly from the merchant's location, which is accessible from the settings. This choice is great for customers who want to avoid paying shipping expenses or need their items sooner. It also benefits merchants who wish to cut shipping costs and simplify order fulfillment. To create Self Pickup, merchants set some information, like a pickup address, pickup hours, pickup instructions, etc.

In Ucraft Next, the Self Pickup can be managed through the platform's Shipping & Delivery subsection of the Settings section. The following key steps must be considered to set up and manage the Self Pickup.

The following screenshot illustrates the input fields of the Self Pickup creation flow.

The Self Pickup Details part includes the Pickup Option Name and Pickup Instructions. Merchants provide clear pickup instructions for customers to pick up their orders. This could include details on where to park or where to find the pickup location, as well as any identification requirements or special instructions.
The Pickup Address part is to decide on a convenient location for customers to pick up their orders. This could be a physical store, warehouse, specified pickup point, or selected parking spot.
The Pickup Hours part is planned to set precise pickup hours for any day of the week so that customers know when to pick up their orders.

Shipping Profile

The other standard delivery technique for E-commerce platforms is the Shipping Profile. It refers to creating a shipping profile that enables businesses to offer customers varying shipping rates and delivery timelines based on the product's location, including numerous rates per zone and adding rules based on product weight, number of items, cart subtotal, and price. This tool for shipping methods management is great for merchants wishing to provide more flexible delivery options to their customers while reducing shipping expenses.

To set up the Shipping Profile in the platform, merchants need to add the following information manually:

• Shipping Zone

• Shipping Type

  • Free Shipping
  • Flat Rate
  • Rate by Weight
  • Rate by Unit
  • Rate by Subtotal

• Shipping Option Name

• Estimated Delivery Time

• Shipping Instructions

The following screenshot illustrates the input fields of the Shipping Profile creation flow.

The Shipping Zone includes Country, Region, State, and City. All regions and cities are automatically chosen when one country is selected. When a country is selected and a state is deselected, all the cities in the country and the region are also deselected.

And only the selected countries are accessible in the public mode, and the other country or countries are hidden when filling in the shipping address. After adding an area, next comes the Shipping Type; by selecting one of the types, the input fields will be customized to reflect the choice. When filling in the Shipping Profile Name and Shipping Option Name, it should be considered that their visibility is as follows:

• Shipping Profile Name - visible on the dashboard
• Shipping Option Name - visible to the public mode

Once the Shipping Profile is created, it will appear in the list of Shipping Profiles and be visible to the public based on the customer's shipping address. Shipping price calculation is included in the public mode, except for the Free Shipping. Depending on various factors (shipping address, shipping types), several tools on the shipping methods management system can be visible and can be calculated shipping charges during the checkout.

The flow is the following; when the customer adds products to their shopping cart, the platform may automatically calculate the shipping price based on the total weight, quantity of units, and cart subtotal. It is essential to focus on the term Minimum Subtotal, which refers to the minimum subtotal amount that a customer must achieve in their cart in order to be approved for a particular shipping method. Customers who have less than $20 in their cart, for example, will be unable to pick that delivery method at checkout if a merchant sets a minimum subtotal of $20 for a given shipping technique. The Minimum Subtotal is available for all Shipping Types.

In the step when the customer fills out their relevant shipping details, such as shipping address, adds a product to the cart, and navigates to the list of Shipping Methods, the shipping cost of each Shipping Type is calculated by the platform based on the information given by the customer and the merchant's configured shipping tool for the shipping methods management system. Eventually, the order's total price is shown to the customer, which includes the shipping fee.

It is worth mentioning that with each Shipping Type, merchants can set a minimum amount for customers to receive Free Shipping. That implies that customers who spend a particular amount of money on products will receive Free Shipping on their order rather than paying additional shipping fees. For example, a merchant may set the amount above $50, which means that if a customer spends $50 or more on the products, they will get Free Shipping on their order.

The Connection of the SMM System with the Public Mode

When the merchant sets up an online store, they have the option to create Shipping Profile, which defines their products' Shipping Types and zones. During the creation of the Shipping Profile, they select the country, and when the customer adds a shipping address that involves a state, city, etc., checks out as a guest, or registers, in this instance, the public mode displays the shipping profiles accessible in that country.

These profiles are created based on delivery time, shipping type, and destination country. For example, a merchant may offer Free Shipping, Flat Rate, Rate by Weight, Rate by Unit, or Rate by Subtotal as different types, with rates and delivery times varying based on the destination country. They may also define specific zones within a country, such as states or cities, with different shipping rates. When a customer adds a shipping address during checkout, the system checks the available shipping option based on the destination country, state, city, zip code, or any other relevant factor. This information is then used to display the available shipping tools of the SMM system.

For instance, if a customer is located in the United States and enters a shipping address in California, the system checks the shipping profile and displays the available tools, such as Flat Rate, Rate by Weight, or Free Shipping, for that address. The available shipping tools may differ if the customer is located in Canada. Offering various shipping tools helps merchants figure out their customers' different needs. For example, some customers may prioritize faster delivery times over lower shipping rates, while others may be willing to wait longer to save on shipping costs. By offering multiple shipping tools and techniques, merchants can provide their customers with greater flexibility and choice, increasing customer satisfaction and loyalty.

GraphQL API Mutations and Queries

Below are described the following mutation and query examples:

• Self Pickup Creation and Manage
• Shipping Profile Creation and Manage
• Shipping Method List Visible on Public

Self Pickup Create and Manage

The following GraphQL code block stands for the Self Pickup. It includes mutation and query fields for creating, updating, deleting, and changing the status of self pickups, as well as retrieving self pickups and their slots. It defines several input types, defines two object types, and also includes various directives.

Self Pickup Create and Manage

type Mutation {
    createSelfPickup(
        input: CreateSelfPickupInput!
    ): SelfPickup!
    updateSelfPickup(
        input: UpdateSelfPickupInput!
    ): SelfPickup!
    deleteSelfPickup(
        input: DeleteSelfPickupInput!
    ): SelfPickup
    changeSelfPickupStatus(
        input: ChangeSelfPickupStatusInput!
    ): Boolean
}

type Query {
    selfPickups: [SelfPickup!]!
    selfPickup(
        input: SelfPickupInput!
    ): SelfPickup
}

input CreateSelfPickupInput {
    inventorySourceId: ID!
    optionName: String!
    instruction: String!
    slotInterval: Int
    sameForAllWeekdays: Boolean!
    slots: [SelfPickupWeekDaySlotsInput!]!
}

input UpdateSelfPickupInput {
    id: ID!
    inventorySourceId: ID!
    optionName: String!
    instruction: String!
    slotInterval: Int
    sameForAllWeekdays: Boolean!
    slots: [SelfPickupWeekDaySlotsInput!]!
}

input DeleteSelfPickupInput {
    id: ID!
}

input ChangeSelfPickupStatusInput {
    id: ID!
    status: Boolean!
}

input SelfPickupInput {
    id: ID!
}

input SelfPickupWeekDaySlotsInput {
    slots: [SelfPickupTimeSlotsInput!]!
    weekDay: WeekDay!
}

input SelfPickupTimeSlotsInput {
    endTime: String!
    startTime: String!
}

type SelfPickup {
    id: ID!
    inventorySourceId: ID!
    inventorySource: InventorySource!
    optionName: String!
    instruction: String!
    slotInterval: Int
    sameForAllWeekdays: Boolean!
    isActive: Boolean!
    slots: [SelfPickupSlots!]!
}

type SelfPickupSlots {
    weekDay: WeekDay!
    slots: [SelfPickupTimeSlots!]!
}

type SelfPickupTimeSlots {
    endTime: String!
    startTime: String!
}

type InventorySource {
    id: ID!
    code: String!
    name: String!
    description: String
    contactName: String!
    contactEmail: String!
    contactNumber: String!
    contactFax: String
    country: String!
    state: String!
    city: String!
    street: String!
    postcode: String!
    priority: Int
    default: Boolean!
    latitude: String
    longitude: String
    status: Boolean!
    company: Company!
    success: String
    totalQty: Int!
}

The table below describes its mutations and queries.

Type	Field	Description
Mutation	createSelfPickup	creates a self pickup object with the specified properties
Mutation	updateSelfPickup	updates an existing self pickup object with new values for the specified properties
Mutation	deleteSelfPickup	deletes an existing self pickup object with the specified ID
Mutation	changeSelfPickupStatus	changes the status of an existing self pickup object with the specified ID
Query	selfPickups	retrieves a list of all self pickups
Query	selfPickup	retrieves a single self pickup object with the specified ID

Shipping Profile Create and Manage

The following schema defines a set of GraphQL mutations and queries related to shipping profiles, including creating, updating, and deleting shipping profiles and changing the status of a shipping profile. It also includes queries for getting shipping profiles and their associated countries. The schema contains several input types for creating and updating shipping profiles, including options for setting shipping times, preparation times, and shipping type options such as free and flat-rate shipping.

Shipping Profile Create and Manage

type Mutation {
    createShippingProfile(
        input: CreateShippingProfileInput!
    ): ShippingProfile!
    updateShippingProfile(
        input: UpdateShippingProfileInput!
    ): ShippingProfile!
    deleteShippingProfile(
        input: DeleteShippingProfileInput!
    ): ShippingProfile!
    changeShippingProfileStatus(
        input: ChangeShippingProfileStatus!
    ): Boolean
}

type Query {
    shippingProfiles: [ShippingProfile!]!
    shippingProfile(
        input: ShippingProfileInput!
    ): ShippingProfile
}

extend type Query {
    shippingAddressCountries: Array!
}

input DeleteShippingProfileInput {
    id: ID!
}

input ChangeShippingProfileStatus {
    id: ID!
    status: Boolean!
}

input ShippingProfileInput {
    id: ID!
}

input CreateShippingProfileInput {
    profileName: String!
    deliveryType: ShippingProfileDeliveryType!
    shippingOptionName: String!
    shippingInstruction: String!
    shippingTime: ShippingProfileShippingTimeInput
    preparationTime: ShippingProfilePreparationTimeInput
    shippingType: ShippingProfileShippingType!
    shippingTypeFreeShippingOptions: ShippingTypeFreeShippingOptionsInput
    shippingTypeFlatRateOptions: ShippingTypeFlatRateOptionsInput
    shippingTypeRateByWeightOptions: ShippingTypeRateByWeightOptionsInput
    shippingTypeRateBySubtotalOptions: ShippingTypeRateBySubtotalOptionsInput
    shippingTypeRateByUnitOptions: ShippingTypeRateByUnitOptionsInput
    minOrderSubtotal: Float
    freeShippingPrice: Float
    shippingProfileCountries: [ShippingProfileCountryInput!]!
}

input UpdateShippingProfileInput {
    id: ID!
    profileName: String!
    deliveryType: ShippingProfileDeliveryType!
    shippingOptionName: String!
    shippingInstruction: String!
    shippingTime: ShippingProfileShippingTimeInput
    preparationTime: ShippingProfilePreparationTimeInput
    shippingType: ShippingProfileShippingType!
    shippingTypeFreeShippingOptions: ShippingTypeFreeShippingOptionsInput
    shippingTypeFlatRateOptions: ShippingTypeFlatRateOptionsInput
    shippingTypeRateByWeightOptions: ShippingTypeRateByWeightOptionsInput
    shippingTypeRateBySubtotalOptions: ShippingTypeRateBySubtotalOptionsInput
    shippingTypeRateByUnitOptions: ShippingTypeRateByUnitOptionsInput
    minOrderSubtotal: Float
    freeShippingPrice: Float
    shippingProfileCountries: [ShippingProfileCountryInput!]!
}

input ShippingProfileShippingTimeInput {
    to: Int!
    from: Int!
}

input ShippingProfilePreparationTimeInput {
    to: Int!
    from: Int!
}

input ShippingTypeFreeShippingOptionsInput {
    shippingType: ShippingProfileShippingType = FREE_SHIPPING
}

input ShippingTypeFlatRateOptionsInput {
    shippingType: ShippingProfileShippingType = FLAT_RATE
    shippingPrice: Float!
    priceCalculationType: ShippingProfileFlatRatePriceCalculationType!
}

input ShippingTypeRateByWeightOptionsInput {
    shippingType: ShippingProfileShippingType = RATE_BY_WEIGHT
    ranges: [ShippingTypeRateByWeightRangeInput!]!
}

input ShippingTypeRateByWeightRangeInput {
    weightTo: Float
    weightFrom: Float!
    price: Float!
}

input ShippingTypeRateBySubtotalOptionsInput {
    shippingType: ShippingProfileShippingType = RATE_BY_SUBTOTAL
    ranges: [ShippingTypeRateBySubtotalRangeInput!]!
}

input ShippingTypeRateBySubtotalRangeInput {
    subtotalTo: Float
    subtotalFrom: Float!
    price: Float!
}

input ShippingTypeRateByUnitOptionsInput {
    shippingType: ShippingProfileShippingType = RATE_BY_UNIT
    ranges: [ShippingTypeRateByUnitRangeInput!]!
}

input ShippingTypeRateByUnitRangeInput {
    unitTo: Int
    unitFrom: Int!
    price: Float!
}

input ShippingProfileCountryInput {
    countryCode: String!
    statesAndCities: Array!
    zipCodes: ZipCodeInput!
}

input ZipCodeInput {
    excluded: [String!]!
    included: [String!]!
}

type ShippingProfile {
    id: ID!
    companyId: ID!
    profileName: String!
    deliveryType: ShippingProfileDeliveryType!
    shippingOptionName: String!
    shippingInstruction: String!
    shippingTime: ShippingProfileShippingTime
    preparationTime: ShippingProfilePreparationTime
    shippingType: ShippingProfileShippingType!
    shippingTypeOptions: ShippingProfileShippingTypeOptions
    minOrderSubtotal: Float
    freeShippingPrice: Float
    isActive: Boolean!
    shippingProfileCountries: [ShippingProfileCountry!]!
}

union ShippingProfileShippingTypeOptions = ShippingTypeFreeShippingOptions | ShippingTypeFlatRateOptions |
    ShippingTypeRateByWeightOptions | ShippingTypeRateBySubtotalOptions | ShippingTypeRateByUnitOptions

type ShippingTypeFreeShippingOptions {
    shippingType: ShippingProfileShippingType!
}

type ShippingTypeFlatRateOptions {
    shippingType: ShippingProfileShippingType!
    shippingPrice: Float!
    priceCalculationType: ShippingProfileFlatRatePriceCalculationType!
}

type ShippingTypeRateByWeightOptions {
    shippingType: ShippingProfileShippingType!
    ranges: [ShippingTypeRateByWeightRange!]!
}

type ShippingTypeRateByWeightRange {
    weightFrom: Float!
    weightTo: Float
    price: Float!
}

type ShippingTypeRateBySubtotalOptions {
    shippingType: ShippingProfileShippingType!
    ranges: [ShippingTypeRateBySubtotalRange!]!
}

type ShippingTypeRateBySubtotalRange {
    subtotalFrom: Float!
    subtotalTo: Float
    price: Float!
}

type ShippingTypeRateByUnitOptions {
    shippingType: ShippingProfileShippingType!
    ranges: [ShippingTypeRateByUnitRange!]!
}

type ShippingTypeRateByUnitRange {
    unitFrom: Int!
    unitTo: Int
    price: Float!
}

type ShippingProfileShippingTime {
    from: Int!
    to: Int!
}

type ShippingProfilePreparationTime {
    from: Int!
    to: Int!
}

type ShippingProfileCountry {
    id: ID!
    companyId: ID!
    countryCode: String!
    shippingProfileId: ID!
    shippingProfile: ShippingProfile!
    statesAndCities: Array!
    zipCodes: ZipCode!
}

type ZipCode {
    included: [String!]!
    excluded: [String!]!
}

The following table describes its mutations and queries.

Type	Field	Description
Mutation	createShippingProfile	creates a new shipping profile with the provided data
Mutation	updateShippingProfile	updates an existing shipping profile with the provided data
Mutation	deleteShippingProfile	deletes an existing shipping profile with the provided ID
Mutation	changeShippingProfileStatus	changes the status of an existing shipping profile with the provided ID
Query	shippingProfiles	retrieves a list of all shipping profiles
Query	shippingProfile	retrieves a single shipping profile by ID
Query	shippingAddressCountries	retrieves a list of all countries associated with the customer's shipping address

The List of Shipping Methods Visible in the Public Mode

The following GraphQL API refers to cart shipping methods and the checkout process. It contains a query to retrieve the shipping methods available for a cart. The response includes information on the shopping cart, delivery, and payment methods.

Shipping Method List Visible on Public

type Query {
    cartShippingMethods: CartShippingMethodResponse
}

type CartShippingMethodResponse {
    success: String
    cart: Cart
    shippingMethods: [ShippingMethod!]!
    paymentMethods: [PaymentResponse!]
    jumpToSection: String
    deliveryTimeSlots: [AvailableDeliveryTimeSlots!]!
}

type ShippingMethod {
    id: ID!
    methodTitle: String!
    methodDescription: String!
    deliveryDate: ShippingRateDeliveryDate
    price: Float!
    formattedPrice: String!
    basePrice: Float!
    formattedBasePrice: String!
    discountAmount: Float!
    formattedDiscountAmount: String!
    baseDiscountAmount: Float!
    formattedBaseDiscountAmount: String!
    freeShippingPrice: Float
    formattedFreeShippingPrice: String
    freeShippingOver: Float
    formattedFreeShippingOver: String
    type: ShippingMethodType!
    selectedTimeSlot: DateWithTimeSlot
    slots: [ShippingRateSlots!]
    inventory_source: InventorySource
}

type ShippingRateDeliveryDate {
    from: String!
    to: String!
}

type DateWithTimeSlot {
    id: ID!
    date: Date!
    startTime: Time!
    endTime: Time!
}

type ShippingRateSlots {
    date: Date!
    slots: [TimeSlots!]!
}

type TimeSlots {
    id: ID!
    endTime: Time!
    startTime: Time!
}

type InventorySource {
    id: ID!
    code: String!
    name: String!
    description: String
    contactName: String!
    contactEmail: String!
    contactNumber: String!
    contactFax: String
    country: String!
    state: String!
    city: String!
    street: String!
    postcode: String!
    priority: Int
    default: Boolean!
    latitude: String
    longitude: String
    status: Boolean!
    company: Company!
    success: String
    totalQty: Int!
}

type AvailableDeliveryTimeSlots {
    date: Date!
    slots: [Slots!]!
}

type Slots {
    id: ID!
    startTime: Time!
    endTime: Time!
}

Activity Log

The Activity Log records all actions or events within a system or application. In the scope of the shipping methods management system, the Activity Log tracks the information on the create, update, delete, and change of the status of the shipping methods management system.

Whether the change relates to the Self Pickup or Shipping Profile makes no difference. If a merchant, for example, creates a new tool for the shipping method or updates an existing one (by changing the price or delivery time), the activity log records the time and date of the action. Details such as the name of the new shipping tool may also be included.

The report logged in the Activity Log helps to maintain transparency since the merchant can see who and when made changes to the shipping tool.