Venddor API - Orders

Orders

Orders are the core of any e-commerce platform. The Orders API allows you to manage customer orders within your Venddor store, including creating, retrieving, updating, and deleting orders.

Key Features:

Complete order lifecycle management
Support for customer-submitted and admin-created orders
Comprehensive order details including products, payment, and shipping information
Order status tracking and updates

Order Workflow

Orders typically follow this workflow within the Venddor system:

Customer adds products to cart and proceeds to checkout
Customer submits order with shipping and payment information
Order is created in the system with "Open" status
Payment is processed (if applicable)
Order status is updated based on payment result
Order is fulfilled and shipped
Order is marked as completed upon delivery

Note: Administrators can also manually create orders in the system, bypassing the standard customer checkout flow. This is useful for phone orders, special customer arrangements, or other scenarios where direct order creation is needed.

Available Endpoints

GET /orders

Retrieves a list of all orders in the system, with optional filtering.

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter orders by status (e.g., "open", "processed", "completed")
user_id	integer	No	Filter orders by customer ID
date_from	string	No	Filter orders created after specified date (format: YYYY-MM-DD)
date_to	string	No	Filter orders created before specified date (format: YYYY-MM-DD)
items_per_page	integer	No	Number of orders to return per page (default: 10, max: 100)
page	integer	No	Page number for pagination (default: 1)

GET /orders/{order_id}

Retrieves detailed information about a specific order.

Path Parameters

Parameter	Type	Required	Description
order_id*	integer	Yes	The unique identifier of the order to retrieve

{
  "order_id": "12345",
  "status": "P",
  "user_id": "42",
  "timestamp": "1618500452",
  "payment": {
    "payment_id": "PM12345",
    "payment_method": "credit_card",
    "status": "paid"
  },
  "products": [
    {
      "item_id": "456",
      "product_id": "101",
      "product_code": "TSH-BLK-L",
      "product_name": "Black T-shirt",
      "price": "19.99",
      "amount": "2"
    },
    {
      "item_id": "457",
      "product_id": "204",
      "product_code": "CAP-RED",
      "product_name": "Red Cap",
      "price": "12.50",
      "amount": "1"
    }
  ],
  "shipping_address": {
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "country": "US",
    "zipcode": "12345"
  },
  "shipping_method": "standard",
  "total": "52.48"
}

POST /orders

Creates a new order in the system.

Request Parameters

Parameter	Type	Required	Description
user_id*	integer	Yes	ID of the customer placing the order
products*	array	Yes	Array of products being ordered
shipping_address*	object	Yes	Shipping address details
shipping_method*	string	Yes	Selected shipping method
payment_method*	string	Yes	Selected payment method

Tip: When creating orders programmatically, you may want to verify product availability and pricing before submitting the order to ensure accurate data.

PUT /orders/{order_id}

Updates an existing order in the system.

Path Parameters

Parameter	Type	Required	Description
order_id*	integer	Yes	The unique identifier of the order to update

Request Parameters

You can update any of the order properties. Only include the fields you want to update.

Important: Updating certain order properties (such as payment status or product list) may have implications for inventory management, customer notifications, and other system processes. Be careful when updating orders and test thoroughly.

DELETE /orders/{order_id}

Deletes an order from the system.

Path Parameters

Parameter	Type	Required	Description
order_id*	integer	Yes	The unique identifier of the order to delete

Caution: Deleting orders permanently removes them from the system. This action cannot be undone. For most business cases, it's recommended to update the order status rather than delete the order completely.

Order Status Codes

The following status codes are used throughout the Orders API:

Code	Status	Description
`O`	Open	Order has been created but not yet processed
`P`	Processing	Order is being processed
`C`	Complete	Order has been fulfilled and completed
`F`	Failed	Order processing failed (e.g., payment declined)
`D`	Declined	Order was declined by the administrator
`B`	Backordered	Order contains products that are currently backordered
`X`	Cancelled	Order was cancelled by the customer or administrator