How to Create an Order for the Buyer API
In this post, we will walk you through creating an order through the Buyer Orders API. You can find the latest here for our developer API docs.
You'll need to have the following information to be able to create this request at the order level:
- Buyer Reference :: A unique way to reference this order for yourself. Ex. Using a UUID to generate a unique id.
- Ordered Date :: The time the order was opened. If your system is near real-time, you can use the current date and time.
- Address :: This will be the address where the order is being shipped to. This is object and requires standard address fields: Address One, City, Province/State, Country, Zip/Postal Code, and Name. Optional fields include Phone Number, Address Two (Often for a specific unit), Company.
- Items :: This will be a list of line items. More details about the structure of the line items is below.
For each line item, the minimum information is:
- Buyer Reference :: This will be how you reference the line time. Once again needs to be unique for each line item. If the specific value doesn't matter to you, use a UUID.
- Quantity :: The number of units being ordered.
- Variant Id :: This value is the variant id within the Modern Dropship. You can find this value by calling the GET /products endpoint on the Modern Dropship API, and retrieving the value from "product.variants.$._id". More information below under "Finding the Variant Object ID" section.
There are other fields that can be included, but all above are the required fields. Here is a sample payload request:
{
"address": {
"addressOne": "123 Main St",
"city": "Waterloo",
"company": "My Business Inc.",
"country": "Canada",
"name": "Jane Doe",
"phoneNumber": "1112223333",
"state": "ON",
"zip": "A1A 1A1"
},
"items": [
{
"buyerReference": "order1_item1",
"quantity": 2,
"variantId": "573ce4477702f4bae7878777"
}
],
"buyerReference": "order1",
"orderedDate": "2020-06-25T19:00:00.000+00:00"
}Below is if all fields are provided:
{
"address": {
"addressOne": "123 Main St",
"city": "Waterloo",
"company": "My Business Inc.",
"country": "Canada",
"name": "Jane Doe",
"phoneNumber": "1112223333",
"state": "ON",
"zip": "A1A 1A1"
},
"items": [
{
"buyerReference": "order1_item1",
"quantity": 2,
"variantId": "573ce4477702f4bae7878777"
}
],
"buyerReference": "order1",
"orderedDate": "2020-06-25T19:00:00.000+00:00",
"note": "This would be a note on the order",
"customerReference": "1001",
"customerEmail": "customer@sample.com"
}Finding the Variant ID for Line Items
In this section, we will find the variant id for referencing the variant on Modern Dropship. We are assuming you have some unique method for referencing variant (a must) and a way to reference the product (optional). This could be a barcode, SKU, primary key within a database, etc.
Modern Dropship Products API
We are going to find the corresponding product, and the variant of that product by calling the GET /buyer/products endpoint.
- Call the GET /buyer/products endpoint, start on page 0. Optionally, provide the "productCode" if you have one.
- Iterate through the array of "data" elements. This is a list of products.
- Within a product, you should loop through the list of "variants". You are trying to match your reference value against the "code" field within the variant. You can also try and match on the "SKU" or "barcode" field.
- You can find the variant id within the "id" field within the variant.
Modern Dropship App (Not Recommended for API users)
This is great method when manually submitting a single order. However, if you are building on top of the API, it's recommended you use the API for finding this information.
- Navigate to the Modern Dropship app.
- Navigate to the Products page (Left menu > "Products")
- Search and find the desired product.
- Open the specific product page.
- Scroll to the "variants" section, click on the specific variant row.
- Within the variant modal, in the top right corner, you should see "Modern Dropship ID". This is the variant id that is required for orders.
Below is a screenshot of the variant model with the Convictionl ID circled.
