Create an Order

Endpoint Overview

This endpoint allows you to create new orders programmatically in your Venddor store. Orders can be created on behalf of existing users or as guest checkouts.

POST /api/orders/

Note: A newly created order will always have "status": "O" (Open). You can change the status only when updating an existing order.

Request Parameters

Pass the following parameters in the HTTP request body according to your specified Content-Type:

Basic Order Information

Parameter	Type	Required	Description
user_id*	integer	Yes	The unique identifier of the user. Can be omitted or set to 0 only if the request includes `user_data`.
payment_id*	integer	Yes	ID of the payment method. The payment method must be available in the store.
shipping_id*	mixed	Yes	ID of the shipping method or an array of shipping method IDs (for multiple product groups). The shipping method must be available in the store and configured for the shipping address.

Multiple Shipping Methods: Beginning with version 4.3.7, you can specify an array of shipping method IDs as the value of shipping_id. The keys of the array would be the keys of the product groups in the cart. This is useful for orders with products from multiple vendors, suppliers, or when products are separated into groups.

Products Information

Parameter	Type	Required	Description
products*	object	Yes	An object with information about the ordered products. Can be structured in two different ways (see below).

Tip: Product prices are taken from the product settings, not from the JSON data. A discount on a product can't be specified in the POST request, but only in a subsequent PUT request.

Way 1: Product IDs as Keys

"products": {
  "241": {
    "amount": "1",
    "product_options": {
      "12": "44",
      "13": "48"
    }
  }
}

Important: If you want your order to have multiple instances of the same product but with different selected options and option combinations, don't use product IDs as keys; use Way 2 instead.

Way 2: Random Numbers as Keys

"products": {
  "1": {
    "product_id": "12",
    "amount": "1",
    "product_options": {
      "3": "12",
      "4": "17"
    }
  },
  "2": {
    "product_id": "12",
    "amount": "2",
    "product_options": {
      "3": "15",
      "4": "19"
    }
  }
}

User Information (for Guest Checkout)

Parameter	Type	Required	Description
user_data	object	Conditional	Required if `user_id` is omitted or set to 0. Contains customer data for guest checkout.

Tip: You can find available country and state codes in the Administration panel under Administration → Shipping & Taxes → States.

User Data Fields

Field	Type	Required	Description
email*	string	Yes	Customer's email address
b_firstname*	string	Yes	First name (billing address)
b_lastname*	string	Yes	Last name (billing address)
b_address*	string	Yes	Street address (billing)
b_city*	string	Yes	City (billing)
b_state*	string	Yes	State code (billing) - 2 characters
b_country*	string	Yes	Country code (billing) - 2 characters
b_zipcode*	string	Yes	Zip/Postal code (billing)
b_phone*	string	Yes	Phone number (billing)
s_firstname*	string	Yes	First name (shipping)
s_lastname*	string	Yes	Last name (shipping)
s_address*	string	Yes	Street address (shipping)
s_city*	string	Yes	City (shipping)
s_state*	string	Yes	State code (shipping) - 2 characters
s_country*	string	Yes	Country code (shipping) - 2 characters
s_zipcode*	string	Yes	Zip/Postal code (shipping)
s_phone*	string	Yes	Phone number (shipping)

Example Requests

Way 1: Create an Order for an Existing User

{
  "user_id": "3",
  "shipping_id": "1",
  "payment_id": "2",
  "products": {
    "1": {
      "product_id": "12",
      "amount": "1"
    },
    "2": {
      "product_id": "13",
      "amount": "2"
    }
  }
}

This request creates an order with the following properties:

Placed by the customer with user_id=3
Using shipping method with shipping_id=1
Using payment method with payment_id=2
Containing one product with product_id=12 and two products with product_id=13

Way 2: Create an Order for a Guest

{
  "user_id": "0",
  "payment_id": "2",
  "shipping_id": "1",
  "products": {
    "1": {
      "product_id": "12",
      "amount": "1"
    },
    "2": {
      "product_id": "13",
      "amount": "2"
    }
  },
  "user_data": {
    "email": "guest@example.com",
    "firstname": "Guest",
    "lastname": "Guest",
    "s_firstname": "Guest",
    "s_lastname": "Guest",
    "s_country": "US",
    "s_city": "Boston",
    "s_state": "MA",
    "s_zipcode": "02125",
    "s_address": "44 Main street",
    "b_firstname": "Guest",
    "b_lastname": "Guest",
    "b_country": "US",
    "b_city": "Boston",
    "b_state": "MA",
    "b_zipcode": "02125",
    "b_address": "44 Main street"
  }
}

Note: Guests must specify their address and contact information at checkout. That's why you must include the user_data object when creating an order for a guest.

Response Format

Success Response (201 Created)

{
  "order_id": "98"
}

Error Response (400 Bad Request)

Returned when the order couldn't be created due to invalid parameters or other issues.

Implementation Notes

When creating orders, consider the following best practices:

Validate product availability before creating an order to avoid inventory issues.
Make sure the shipping and payment methods specified are active and available.
For guest orders, provide complete and valid user data to ensure successful order processing.
When working with options, use the correct option IDs and variant IDs for the products.
Test your implementation with small orders before processing large or complex orders.