Order History and Reorder Functionality Using Propeller Commerce GraphQL API

In B2B commerce, customers frequently reorder products, making it essential to provide a seamless way to access previous orders and quickly reorder the same items. In this tutorial, we'll explore how to implement order history and reorder functionality using the Propeller Commerce GraphQL API.

Why It’s Important

B2B customers often have recurring needs, and being able to easily reorder from previous purchases can drastically improve user experience and retention. Offering a streamlined way to manage order history and reorder items in bulk enhances customer satisfaction and saves time.

Key Topics Covered

1. Fetching Order History
2. Filtering and Searching Order History
3. Displaying Order Details
4. Fetching Shipping Information and Tracking Code
5. Implementing a Reorder Button

Let’s dive into each of these areas.

---

1. Fetching Order History

To display order history, the Propeller Commerce GraphQL API provides a orders query that retrieves all orders for a customer. You can use this query to show a list of past orders along with relevant details such as order date, status, and total amount.

Query Example: Fetching Orders

query GetOrders() { 
 orders(input: {status:["NEW"]}) {
        start
        end
        itemsFound
        offset
        page
        pages
        items {
            id
            status
            date
            total {
                gross
                net
                tax
                taxPercentages {
                    percentage
                    total
                }
            }
            items {
                id
                quantity
            }
        }
  }
}

Query breakdown:

• Filtering by status helps manage different types of orders
• Fields like start, end, itemsFound, offset, page, and pages help handle large datasets and allow for efficient pagination.
• Each order in the result contains:
  • id: The unique identifier for the order.
  • status: The current status of the order (e.g., "NEW", "PROCESSING", "COMPLETED").
  • date: The date the order was placed.
  • total: Financial details of the order:
    • gross: The total amount for the order excluding taxes.
    • net: The total amount for the order including taxes.
    • tax: The total tax amount applied to the order.
    • taxPercentages: A breakdown of the tax percentages applied:
      • percentage: The tax percentage rate (e.g., 5%, 10%).
      • total: The total tax amount corresponding to the percentage.

This structure is ideal for B2B platforms where users need to track their orders, review the status, and manage their order history efficiently.

2. Filtering and Searching Order History

Filtering and searching order history using the Propeller GraphQL v2 API involves using the orders query with various input filters. These filters allow you to narrow down the results based on specific criteria, such as order status, date range, or other relevant attributes. The most common filters that are applied to the orders query to limit the results are the following ones:

• status: Filter orders by their current status (e.g. NEW, CONFIRMED, VALIDATED, ARCHIVED). This helps users focus on orders that are in specific stages of the order lifecycle.
• createdAt: Filter orders by a date range. This field allows you to retrieve orders placed within a specific period.
• price: Filter orders by a price range. This field allows you to retrieve orders within a specific price range.
• userId: Retrieve orders associated with a specific user. This is useful for fetching order history for a logged-in customer.
• companyIds: Filter orders by company, particularly useful in B2B contexts where multiple users can place orders under the same company.
• type: Filter by the type of order, such as “dropshipment”, “purchase” or “quotation”

Query Example: Filtering by User and Company In B2B scenarios, orders may be filtered by the user who placed them or the company associated with the order. You can use the userId and companyIds fields to filter orders based on these criteria.

query GetOrders() { 
 orders(input: {userId: [12345], companyIds: [678]}) {
    items {
        id
        status
        date
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

Query Example: Filtering by Date Range You can filter orders placed within a specific date range using the createdAt field.

query GetOrders() { 
 orders(input:{ createdAt: { lessThan:"2024-12-31",greaterThan:"2024-01-01" } }) {
    items {
        id
        status
        date
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

This query will return all orders placed between January 1, 2024, and December 31, 2024.

Query Example: Combining Filters You can combine multiple filters in a single query to create more specific searches. For instance, you might want to fetch "NEW" orders placed in the last 30 days for a particular user.

query GetOrders() { 
 orders(input: {
    userId: [12345], 
    status: ["NEW"], 
    createdAt: { lessThan:"2024-09-30",greaterThan:"2024-09-01" }
  }) {
    items {
        id
        status
        date
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

Query Example: Handling Pagination For large datasets, you may want to implement pagination. Propeller's API supports pagination with fields such as offset and page.

query GetOrders() { 
 orders(input: {type: [dropshipment], offset: 5}) {
    itemsFound
    start
    end
    page
    pages
    items {
        id
        status
        date
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

Using these filtering and searching techniques, you can implement a robust order history view that allows customers to easily manage and search through their past orders.

3. Displaying Order Details and Shipment Tracking

Each order contains detailed information such as ordered items, shipment tracking codes, payment status, and shipping methods. The order query provides insights into individual orders, including its general details, total costs, addresses, ordered items, payment data, and postage data. The orderId is used to identify the specific order.

Query Example: Displaying Order Details

query GetOrderDetails {
  order(orderId: 123) {
    cartId
    currency
    date
    email
    id
    reference
    remarks
    status
    type
    userId
    total {
      gross
      net
      tax
      taxPercentages {
        percentage
        total
      }
    }
    deliveryAddress: addresses(type: delivery) {
      firstName
      middleName
      lastName
      email
      country
      city
      street
      number
      numberExtension
      postalCode
      company
      type
    }
    invoiceAddress: addresses(type: invoice) {
      firstName
      middleName
      lastName
      email
      country
      city
      street
      number
      numberExtension
      postalCode
      company
      type
    }
    items {
      orderId
      productId
      class
      name
      price
      priceTotal
      priceTotalNet
      tax
      taxCode
      taxPercentage
      discount
      quantity
      sku
      notes
      product {
        sku
        names {
          value
          language
        }
        slugs {
          value
          language
        }
      }
    }
    paymentData {
      gross
      method
      net
      status
      statusDate
      tax
      taxPercentage
    }
    postageData {
      method
      gross
      net
      tax
      taxPercentage
    }
  }
}

This query retrieves detailed information about a specific order, including:

• Order identification and basic details.
• Total amounts (gross, net, and tax) for the entire order.
• Addresses (both delivery and invoice).
• Items included in the order, with detailed pricing and tax breakdown.
• Payment details including method, status, and tax.
• Postage details including shipping method and costs.

These fields are designed to provide a comprehensive view of the order, making it easy to display all relevant information to both the customer and the internal systems handling order fulfillment.

4. Fetching Shipping Information and Tracking Code

To fetch the shipping information and the shipment tracking code for a specific order, you will include the shipments field in the order query. This field contains details about shipments related to the order, including shipment status and trackAndTrace codes.

Query Example: Order shipments

query GetOrder {
  order(orderId: 123) {
    id
    type
    userId
    total {
      gross
      net
      tax
    }
    shipments {
      date
      id
      orderId
      printDate
      status
      totalDiscountValue
      totalGross
      totalNet
      totalTax
      items {
        id
        shipmentId
        orderItemId
        productId
        quantity
      }
      trackAndTrace {
        id
        orderId
        carrierId
        shipmentId
        code
      }
    }
    items {
      orderId
      productId
      name
      price
      quantity
    }
    paymentData {
      gross
      method
      net
      status
    }
    postageData {
      method
      gross
      net
      partialDeliveryAllowed
    }
  }
}

This query retrieves all relevant data about a specific order:

• Order details: General information like the order type, user who placed it, and the total amount.
• Shipments: Information about shipments related to the order, including shipment status and track-and-trace codes.
• Items: Products ordered, with prices and quantities.
• Payment data: Payment details, including the method and current status.
• Postage data: Information about the shipping method, shipping costs, and whether partial delivery is allowed.

5. Implementing a Reorder Button

One of the key features for B2B customers is the ability to reorder items quickly. Using the Propeller API, you can implement a "Reorder" button that fetches all items from a previous order and adds them to the cart in bulk.

To reorder, the API allows you to use the cartAddItem mutation to add items from a previous order.

Here’s how you can implement the "Reorder" functionality step-by-step using the Propeller Commerce GraphQL API.

Key Steps for Reorder Functionality

1. Fetch the Previous Order Details The first step is to retrieve the details of the specific order the customer wants to reorder. This can be done using the order query.

Query Example

query GetOrderDetails {
  order(orderId: 123) {
    id
    items {
      productId
      quantity
      price
      sku
      name
    }
  }
}

2. Extract Product Data from the Order Once you fetch the order details, you will extract the relevant product information such as productId, quantity and price. This data will be used to add the items back into the shopping cart.

const orderItems = order.items.map(item => ({
  productId: item.productId,
  quantity: item.quantity,
  price: item.price,
}));

3. Add Products to the Cart using cartAddItem Mutation To reorder the products, you’ll need to use the cartAddItem mutation to add the previously ordered products to the current shopping cart. This mutation allows you to specify the products and their quantities.

Query Example

mutation AddToCart {
   cartAddItem(
    id: "018dcc9a-f965-7434-8fad-369aa9a8c276"
    input: { productId: 67890, quantity: 2 }
  ) {
    items {
      itemId
      productId
      quantity
      price
      priceNet
    }
    total {
      totalGross
      totalNet
    }
  }
}

4. Optional: Check Stock Availability Before adding items to the cart, you may want to check if the products are still in stock. This can be done using the product query to verify the stock status of each product.

Query Example

query CheckProductStock {
  product(productId: 67890) {
    inventory {
      totalQuantity  
    }
  }
}

5. Display a Success Message or Redirect the User to the Cart Once the reorder action is complete and the products are added to the cart, you can display a success message to the user or redirect them to the cart page for review.

Conclusion

In this tutorial, we explored how to implement Order History and Reorder Functionality using the Propeller Commerce GraphQL API, providing users with an enhanced shopping experience. By leveraging the API's robust querying capabilities, you can seamlessly display a user's past orders, offer detailed order and shipment tracking, and allow easy reordering of previous purchases with just a few clicks.

This functionality is particularly valuable in B2B environments where repeat orders are common. Implementing these features can significantly improve user satisfaction and streamline the purchasing process, ultimately boosting customer loyalty and driving additional sales.

With the orders query, you can efficiently retrieve detailed order histories, and by using the cartAddItem mutation, you can enable the convenient reordering of products. By integrating these tools, businesses can provide a user-friendly interface that simplifies repeat purchases, improves customer retention, and increases overall revenue.

By following the steps in this tutorial, you now have the foundation to build a comprehensive and seamless order management experience for your users.