Orders and Order Management

Overview

The Orders object in the POS Portal API is central to managing customer purchases, from the initial order creation to tracking and fulfilling those orders. This guide provides a step-by-step process for creating and managing orders using the POS Portal API.

For a quick review of what the workflow should look like to submit an order, please review the image below (click on the image to enlarge it):

Creating an Order

Creating an order involves several key steps, including retrieving product details, configuring the order items, and finalizing the order. Below is a comprehensive guide to help you through the process.

Step 1: Retrieve Product Information

Before creating an order, you need to gather details about the products you want to include. You can retrieve product information using the following endpoints:

• Get Product Details
  Use this endpoint to fetch detailed information about a specific product. This will provide you with the product name, description, price, available configurations, and more.

  GET /v2/products/{id}
  

• Get Product Configurations
  If the product has configurable options (e.g., size, color, features), you can retrieve those using this endpoint.

  GET /v2/products/{id}/configurations
  

• Get Bundled Products
  If the product is part of a bundle, you can retrieve the details of the bundle to understand what products are included.

  GET /v2/bundles/{id}
  
  

Step 2: Prepare the Order

Once you have the necessary product information, you can start preparing the order:

• Create a New Order
  To begin, create a new order by sending a POST request to the orders endpoint. You will need to include details such as the merchant ID, order items, and any special instructions. See the POST Orders request for more detail on what the JSON payload should contain.

Step 3: Add Order Items

You may need to add additional items to the order or update existing items.

• Add Items to an Existing Order
  Use this endpoint to add new items to an order that has already been created.

  POST /v2/orders/{id}/items
  

• Update Order Items
  If you need to change the quantity or configuration of an item in an order, you can update the specific item.

  PATCH /v2/orders/{id}/items/{itemId}
  

Step 4: Retrieve and Manage the Order

After creating an order, you can retrieve and manage it using several resources.

• Get Order Details
  Retrieve detailed information about an existing order, including all items, configurations, and shipping details.

  GET /v2/orders/{id}
  

• Manage Order Status

  • DRAFT (set by Customer)
    When creating a new order, you can initialize it in a DRAFT status.

    • Allows you to immediately retrieve the order from POS Portal.
    • You can add/remove items and update device configurations while in this state.
    • When the order is ready for fulfillment, you must PATCH the order to OPEN.

  • OPEN (set by Customer)
    Indicates that the order is finalized and ready for processing.

    • Once set to OPEN, POS Portal begins fulfillment.
    • At this stage, no further structural changes (items/configurations) can be made.

  PATCH /v2/orders/{id}
  

• Delete an Order
  If an order needs to be removed, you can delete it using this endpoint.

  DELETE /v2/orders/{id}
  

Step 5: Shipping and Delivery

Shipping is a critical component of order management. After finalizing the order items, you need to handle shipping details.

• Get Shipping Options
  Retrieve available shipping methods and costs.

  GET /v2/orders/{id}/shipping
  

Step 6: Finalizing the Order

Once all items and shipping details are confirmed, the order can be finalized.

• Submit the Order
  Finalize the order by confirming all details and submitting it for processing.

  PATCH /v2/orders/{id}
  

NOTE:

To get KSIs and DIDs (as well as serial number, product id, etc.) after the order ships, you will need to make an API call to get deployedequipment. You can utilize a number of query parameters, to get deployedequipment, including orderId & p2pe. Note that the ksnScans list will only be included in the response when specified in the select query parameter (see sample request below).

{
  "ksnScans": [
    {
      "ksi": "FFFF101010",
      "did": "CDB04",
      "scanDate": "2017-12-08T16:28:22Z"
    },
    {
      "ksi": "FFFF121212",
      "did": "6345C",
      "scanDate": "2017-12-08T16:28:22Z"
    }
  ],
  "p2pe": true
}

Summary

Managing orders with the POS Portal API is a streamlined process that involves retrieving product details, configuring the order, adding items, managing shipping, and finalizing the order. By following the steps outlined in this guide, you can efficiently create and manage orders, ensuring timely and accurate delivery to your customers.

For more detailed information on the Order endpoint and its parameters, please refer to the POS Portal API Documentation.