Orders

POST /api/orders

Description

Create an order in the Insight Hero Database, filtering items to include only those with discount codes from the shop's DiscountCodes generated by Insight Hero where the variantId matches the target.

Request Body

Field	Type	Required	Description
orderId	Number	Yes	Unique order ID (e.g., from client system)
orderCreatedAt	String	Yes	ISO timestamp (e.g., "2025-03-11T10:00:00Z")
items	Array	Yes	List of order items
items[].productId	Number	Yes	Product ID
items[].variantId	Number	Yes	Variant ID
items[].quantity	Number	Yes	Number of units
items[].price	Number	Yes	Price per unit
items[].discountCode	String	No	Discount code (must match shop's records)
items[].discountValue	Number	No	Discount amount per unit
items[].variantName	String	No	Variant name (e.g., "Red")
items[].variantProductName	String	No	Product name (e.g., "T-Shirt")

Example Request Body

{
    "orderId": 12345,
    "orderCreatedAt": "2025-03-11T10:00:00Z",
    "items": [
        {
            "productId": 1001,
            "variantId": 2001,
            "quantity": 2,
            "price": 50.00,
            "discountCode": "BID-WEU48Q",
            "discountValue": 10.00,
            "variantName": "Red",
            "variantProductName": "T-Shirt"
        },
        {
            "productId": 1001,
            "variantId": 2002,
            "quantity": 1,
            "price": 50.00,
            "discountCode": "invalid",
            "discountValue": 5.00,
            "variantName": "Blue",
            "variantProductName": "T-Shirt"
        }
    ]
}

Responses

Success (Status: 201 Created)

{
    "message": "Order created successfully",
    "order": {
        "orderId": 12345,
        "price": 80.00,
        "discountAmount": 20.00,
        "discountCode": "BID-WEU48Q",
        "variantDetails": [
            {
                "productId": 1001,
                "variantId": 2001,
                "quantity": 2,
                "price": 50.00,
                "discountCode": "BID-WEU48Q",
                "discountValue": 10.00,
                "variantName": "Red",
                "variantProductName": "T-Shirt"
            }
        ]
    }
}

Error (Status: 400 Bad Request)

{
    "error": "Failed Create Order: Failed Process Order: No items with valid discount codes, matching variant IDs, and correct discount values from this shop"
}

GET /api/orders/:orderId

Description

Retrieve a specific order by its orderId, scoped to the authenticated shop. Returns detailed order information if found.

Path Parameter

Parameter	Type	Required	Description
orderId	Number	Yes	Unique order ID

Example Request

GET /api/orders/12345

Responses

The response includes the order details if found, or an error if the order doesn’t exist or isn’t associated with the shop.

Response Fields

Field	Type	Description
message	String	A human-readable success message
order	Object	The order details (null if not found in error cases)
order.orderId	Number	lient-provided order ID
order.price	Number	Total price after discounts
order.discountAmount	Number	Total discount applied across all items
order.discountCode	String	Comma-separated list of discount codes used in the order
order.variantDetails	Array	List of items with their details
order.variantDetails[].productId	Number	Product ID
order.variantDetails[].variantId	Number	Variant ID
order.variantDetails[].quantity	Number	Number of units
order.variantDetails[].price	Number	Price per unit before discount
order.variantDetails[].discountCode	String	Discount code applied (if any)
order.variantDetails[].discountValue	Number	Discount amount per unit
order.variantDetails[].variantName	String	Variant name (optional)
order.variantDetails[].variantProductName	String	Product name (optional)

Success (Status: 200 OK)

{
    "message": "Order retrieved successfully",
    "order": {
        "orderId": 12345,
        "price": 80.00,
        "discountAmount": 20.00,
        "discountCode": "BID-WEU48Q",
        "variantDetails": [
            {
                "productId": 1001,
                "variantId": 2001,
                "quantity": 2,
                "price": 50.00,
                "discountCode": "BID-WEU48Q",
                "discountValue": 10.00,
                "variantName": "Red",
                "variantProductName": "T-Shirt"
            }
        ]
    }
}

Error (Status: 400 Bad Request)

• Invalid orderId:

{ "error": "Invalid orderId: must be a number" }

Error (Status: 404 Not Found)

• Order Not Found:

{ "error": "Order with orderId 12345 not found for this shop" }

DELETE /api/orders/:orderId

Description

Delete an order by its orderId (e.g., in case of order cancellation), scoped to the authenticated shop.

Path Parameter

Parameter	Type	Required	Description
orderId	Number	Yes	Unique order ID

Example Request

DELETE /api/orders/12345

Responses

Success (Status: 200 OK)

{
    "message": "Order 12345 deleted successfully"
}

Error (Status: 404 Not Found)

• Order Not Found:

{ "error": "Order not found or does not belong to this shop" }

• Invalid orderId:

{ "error": "Invalid orderId" }