Order Retrieval Endpoint

Overview

This endpoint is designed to retrieve a user's order data from a Shopify store without requiring direct interaction with the Shopify API. It processes a request that includes the user's email and the Shopify store ID, fetches the relevant order details, and returns a structured response with the order information, including fulfillment status and product images.

Endpoint

URL: ‘https://streamline-connector-for-voiceflow.gadget.app/order-data’

Method: GET

Query Parameters

• email: (string) The email address of the user whose orders are being retrieved.

• shopId: (string) The ID of the Shopify store from which to retrieve the orders.

• orderNumber: (string) The number of the order placed.

Note: At least one of the following, email or orderNumber, is required both of them can be used at the same time too. shopId is always required.

Crafting Your Endpoint

To use the endpoint, construct a GET request URL by including the required query parameters in the following format as needed:

Example 1: Use email captured in Voiceflow (it works likewise with orderNumber)

If you use our Retrieve Orders Voiceflow function you will find that the only input variable is the email. This email is used for the endpoint. All you need to do is replace the example email ("user@example.com") for "${email}". This way when the function executes the endpoint will be filled with the corresponding email.

E.g using shopId = 424242 and including the variable:

https://streamline-connector-for-voiceflow.gadget.app/order-data?email=${email}&shopId=424242

Note: if using variables in the endpoint, whether are email or orderNumber the endpoint must be between " ` " (e.g. requestUrl = `https://streamline-connector-for-voiceflow.gadget.app/order-data?email=${email}&shopId=424242` )

Example 2: Retrieve all orders for a user (just email)

If you want to fetch all orders for the user user@example.com from the Shopify store with ID 86025044251, your endpoint would look like this:

https://streamline-connector-for-voiceflow.gadget.app/order-data?email=user@example.com&shopId=86025044251

Example 3: Retrieve a specific order (orderNumber and email used simultaneously)

If you want to retrieve the details of a specific order (e.g., order number 98765) for the same user and store, your endpoint would look like this:

https://streamline-connector-for-voiceflow.gadget.app/order-data?email=user@example.com&shopId=86025044251&orderNumber=98765

Response Format

Success Response (HTTP 200)

If the request is successful and orders are found, the endpoint returns a JSON response with the following structure:

{
  "success": true,
  "message": "if you're seeing this, you're authenticated! You sent the email: example@example.com",
  "data": [
    {
      "id": "order_id",
      "name": "order_name",
      "total_price": "order_total_price",
      "order_status": "Processed",
      "date": "order_date",
      "order_status_url": "order_status_url",
      "product_image": "product_image_url",
      "fulfillment_status": "fulfillment_status"
    },
    ...
  ]
}

success: Indicates whether the request was successful (true).

message: A message confirming the email and successful authentication.

data: An array of objects representing the user's orders.

• id: The unique identifier for the order.

• name: The name of the order.

• total_price: The total price of the order.

• order_status: The current status of the order, e.g., "Processed".

• date: The date when the order was created.

• order_status_url: A URL where the user can check the order status.

• product_image: The URL of the product image associated with the order. If no image is found, it will return "image not found".

• fulfillment_status: The fulfillment status of the order.

Error Responses

• Shop Not Subscribed (HTTP 400) If the Shopify store is on a "Free" subscription plan:

{
  "success": false,
  "message": "Shop not subscribed"
}

• Missing Email (HTTP 400) If the email parameter is missing:

{
  "success": false,
  "message": "Missing email"
}

• Order Not Found (HTTP 404) If no orders are found for the provided email:

{
  "success": false,
  "message": "Order not found"
}

Data Retrieval Process

1. Input Validation:

   • The function first extracts the email and shopId from the query parameters.

   • It checks if the shopId corresponds to a valid Shopify store and whether the store is subscribed to a plan that allows order retrieval.

2. Email Normalization:

   • The provided email is converted to lowercase to ensure consistency in searching.

3. Order Search:

   • Orders are retrieved from the database based on the normalized email and shop ID.

   • Orders are sorted by creation date in descending order to return the most recent orders first.

4. Fulfillment Status Retrieval:

   • For each order, the latest fulfillment status is retrieved. If no status is found, it defaults to "Processed".

5. Product Image Retrieval:

   • The product image associated with the order line items is retrieved. If no image is found, it defaults to "image not found".

6. Response Construction:

   • The function compiles the retrieved data into a structured response and sends it back to the client.