Create Order

The POST endpoint creates a new order with the specified details.

Endpoint

• URL: /orders
• Method: POST

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
Content-Type	string	Must be application/json.
accessToken	string	Access token for authentication. (required)

Request Body

The request body must include details of the order to be created. Below are the fields required:

Field	Type	Requirements/Notes
customer	joiId	Required - Unique identifier for the customer.
paymentStatus	enum	Required - Valid values: "unpaid", "authorized", "declined", .., "refunded".
orderStatus	enum	Required - Valid values: "fulfilled", "pending", ..., "cancelled".
fulfilledItems	array of objects	Items defined in Fulfilled Items.
taxAmount	number	Total tax amount for the order.
billingAddress	joiId	Identifier for the existing billing address.
newBillingAddress	object	Defined in New Billing Address.
paymentTerm	joiId	Id of payment term assigned for that company
shippingAddressId	joiId	Identifier for the existing shipping address.
newShippingAddress	object	Defined in New Shipping Address.
orderedAt	string	Date and time when the order was placed.
refundedAmount	number	Total refunded amount.
shippingCost	number	Cost of shipping, must be positive or zero.
shippingLabel	string	Label for the shipping, allows empty or null.
currency	object	Properties: currency (2-char string), symbol (2-char string).
lineItems	array of objects	Required - Items defined in Line Items.
metaFields	array of objects	Collection of metaField objects.

Fulfilled Items

Field	Type	Requirements/Notes
items	array of objects	Items defined in Fulfilled Item.
carrier	string	Carrier used for shipping.
trackingNumber	string	Tracking number for the shipment.
trackingUrl	string	URL for tracking the shipment.
fulfilledAt	string	Date and time when the order was fulfilled.

Fulfilled Item

Field	Type	Requirements/Notes
lineItemId	string	Identifier for the line item.
quantity	number	Required - Must be positive or zero.
metaField	object	Properties: code (string), value (string).
sku	string	Stock Keeping Unit.
options	array of objects	Properties: name (string), value (string).

Product Options

Field	Type	Requirements/Notes
optionName	string	Non-empty string for option name.
optionValueLabel	string	Non-empty string for option value label.
optionValue	string	Non-empty string for the option value.

Product Discount

Field	Type	Requirements/Notes
id	joiId	Unique identifier for the discount.
name	string	Name of the discount.
discountedAmount	number	Required - The amount of the discount.

Line Items

Field	Type	Requirements/Notes
productId	joiId	Identifier for the product.
variantId	joiId	Identifier for the product variant.
quantity	number	Required - Must be positive or zero.
discounts	array of objects	Discounts applied, defined in Product Discount.
discountAmount	number	Total discount amount.
price	number	Required - Price of the line item.
fulfilledQuantity	number	Must be positive or zero.
returned	boolean	Indicates if the item was returned.

New Shipping Address

Field	Type	Requirements/Notes
companyName	string	Company name of this contact (Optional).
companyEmail	string	Company email of the contact (Optional).
firstName	string	Min Length: 1
lastName	string	Min Length: 1, Allows empty string ("").
address1	string	Min Length: 1, Max Length: 100
address2	string	Min Length: 1, Max Length: 100
phoneNumber	string	Min Length: 1, Max Length: 100
city	string	Min Length: 1, Max Length: 100
state	string	Min Length: 1, Max Length: 100
country	string	Min Length: 1, Max Length: 100
zipcode	string	Min Length: 1, Max Length: 100

New Billing Address

Field	Type	Requirements/Notes
companyName	string	Company name of this contact (Optional).
companyEmail	string	Company email of the contact (Optional).
firstName	string	Min Length: 3, Max Length: 20
lastName	string	Min Length: 3, Max Length: 20, Allows empty string ("").
address1	string	Min Length: 1, Max Length: 100
address2	string	Min Length: 1, Max Length: 100
phoneNumber	string	Min Length: 1, Max Length: 100
city	string	Min Length: 1, Max Length: 100
state	string	Min Length: 1, Max Length: 100
country	string	Min Length: 1, Max Length: 100
zipcode	string	Min Length: 1, Max Length: 100

Notes

• The orderSchema requires either shippingAddressId or newShippingAddress, and either billingAddress or newBillingAddress to be present.

Sample Request Body

{
  "customer": "6328113ba105cf37af7f623b",
  "paymentStatus": "paid",
  "orderStatus": "fulfilled",
  "taxAmount": 0,
  "billingAddress": "63356b3b3a6353a69043680b",
  "shippingAddressId": "63356b3b3a6353a69043680c",
  "newShippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "65161861",
    "address1": "12/4, test st",
    "address2": "",
    "city": "Elizabeth",
    "state": "NJ",
    "country": "US",
    "zipcode": "07202"
  },
  "refundedAmount": 0,
  "shippingCost": 0,
  "shippingLabel": "UPS",
  "shipmentDetails": {
    "trackingNumber": "8498461648",
    "carrier": "something",
    "fulfilledAt": "2022-10-18",
    "timeEstimate": "2 days"
  },
  "currency": {
    "currency": "USD",
    "symbol": "$"
  },
  "metaFields": [
    {
      "label": "orderId",
      "value": "#123445363",
      "displayStorefront": true
    }
  ],
  "lineItems": [
    {
      "productId": "636d07be0438c42bc4d455e3",
      "variantId": "636d07be0438c42bc4d455f2",
      "quantity": 10,
      "price": 31.84
    }
  ],
  "fulfilledItems": [
    {
      "items": [
        {
          "lineItemId": "",
          "quantity": ""
        }
      ],
      "carrier": "something",
      "trackingNumber": "8498461648",
      "fulfilledAt": "2022-10-20"
    }
  ]
}

Response

• Status Code: 200 Created

Success Response Body

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": "<Order ID>"
    //...
  }
}

Success Response Structure

Field	Type	Description
success	boolean	Indicates whether the request was successful.
message	string	Provides a descriptive message about the outcome.
data	object	Contains the details of the newly created order. Defines in Order Object.

Error Responses

Status Code	Description
400	Bad Request: Invalid input data.
401	Unauthorized: Access token is invalid or missing.
500	Internal Server Error: An error occurred on the server.

Notes

• Ensure all required fields are provided in the request body.
• Provide a valid and active access token in the request header to authenticate your request.
• The response body will include details about the created order, such as the order ID and other order information.