• Version: 1.2.0

Orders

Orders are collections of products and product variations that a customer is purchasing, but may not have paid for yet. Orders can also track returns, refunds, or delivery mismatches. All orders will remain until they are deleted, so if they are associated with a customer, you can build and maintain a customer history and provide that history to customers on their account page.

You can create an order manually using the https://api.molt.in/v1/orders endpoint or by processing a cart with the checkout endpoint. Both will create the same object, though the checkout endpoint provides more convenience if your store uses carts. Like carts, an order can contain one or more products or variations and, optionally, a link to a customer. However, orders also contain shipping information, a payment gateway, and billing and shipping addresses.

Key Type Required Unique Details
customer Integer or String No No The ID number or email address of the customer to associate with this order.
gateway String No No The slug of the gateway to use to process payment.
status Choice Yes No The current payment, shipment, or other state that this order is currently in. Can be one of the following: unpaid (default), paid, dispatched, processing, refunded, cancelled, failed, declined, mismatch, or partial_refund.
subtotal decimal Yes No The total of the order before shipping and exchange rates.
shipping_price decimal No No The cost of the shipping.
total decimal Yes No The total value of the order.
currency ID number Yes No The ID number of the currency in which this order will be paid.
currency_code String Yes No The three-letter code that identifies the currency used.
exchange_rate decimal Yes No The amount of the provided currency equal to one of the store default currency.
shipping Integer No No The ID number of the shipping method the order will use.
bill_to Integer or Array No No The ID number or details of the billing address. If passing an array, the array items are the same as those used to create addresses.
ship_to Integer or Array No No The ID number or details of the shipping address. If both addresses are the same, you can set ship_to=bill_to.

Before using orders, you’ll need to create them with the https://api.molt.in/v1/orders or https://api.molt.in/v1/carts/checkout endpoint. Orders are the last step in a store transaction, so they can be used to receive payment, track shipping, or deliver customer histories.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Order

If you haven’t converted a cart into an order using the checkout endpoint, you can create an order manually. POST the required data fields to the https://api.molt.in/v1/orders endpoint.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/orders \
 -H "Authorization: Bearer XXXX" \
 -d "status=unpaid" \
 -d "subtotal=100" \
 -d "total=105" \
 -d "currency=<CURRENCY ID>" \
 -d "currency_code=USD" \
 -d "exchange_rate=1"

This is a much more basic set of information than you would have if you created the order through the checkout endpoint. You can add gateway, billing and shipping addresses, and the items that are part of the order, but they are all optional to create the order. On success, this call returns a 201 Created HTML status code and the following limited order information.

{
 "status":true,
 "result":
 {
  "id":"1069799123244286525",
  "order":null,
  "created_at":"2015-09-08 22:06:52",
  "updated_at":"2015-09-08 22:06:52",
  "customer":null,
  "gateway":null,
  "status":
  {
   "value":"Unpaid",
   "data":
   {
    "key":"unpaid",
    "value":"Unpaid"
   }
  },
  "subtotal":100,
  "shipping_price":0,
  "total":105,
  "currency":
  {
   "value":"United States Dollar",
   "data":
   {
    "id":"1045136579997204963",
    "code":"USD",
    "title":"United States Dollar",
    "enabled":true,
    "modifier":"+0",
    "exchange_rate":0,
    "format":"\\u0024{price}",
    "decimal_point":".",
    "thousand_point":",",
    "rounding":null,
    "default":false,
    "created_at":null,
    "updated_at":null
   }
  },
  "currency_code":"USD",
  "exchange_rate":1,
  "shipping":null,
  "ship_to":null,
  "bill_to":null,
  "totals":
  {
   "formatted":
   {
    "subtotal":"\\u0024100.00",
    "total":"\\u0024105.00",
    "shipping_price":"\\u00240.00",
    "tax":"\\u00240.00"
   },
   "rounded":
   {
    "subtotal":100,
    "total":105,
    "shipping_price":0,
    "tax":0
   },
   "raw":
   {
    "subtotal":100,
    "total":105,
    "shipping_price":0,
    "tax":0
   }
  },
  "count":0
 }
}

The calls below that directly affect orders will return information in this same format. Calls that affect individual order items will return information in a different format.

Retrieve Orders

You have two methods to retrieve order information. The first requires that you know the ID number of the order that you want, and it returns solely the information for that one order. The second returns an array of orders that you can limit by field values, specify a maximum number to return, and offset the start of the array. Using the last two options, you can paginate results by increasing the offset of a search by the previous maximum.

Retrieve a Single Order by ID

You can GET information for a single order by adding the ID number to the orders endpoint. No additional data fields are required.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/orders/:id \
 -H "Authorization: Bearer XXXX"

A successful call returns a 200 OK status code.

Retrieve a List of All Orders

Using the https://api.molt.in/v1/orders endpoint, you can return an array that contains all of the orders that you have created. Please note that depending how much data your store contains, this could be a very large JSON array. We recommend that you limit your searches by field values (as shown in the next section) or specify individual order ID numbers.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/orders \
 -H "Authorization: Bearer XXXX"

On success, this returns 200 OK and an array of order information, as shown in the Create an Order section.

Search for Orders by data fields

Instead of returning all of your store’s orders, you can return only orders that match on specified field values. This lets you do things like return all orders associated with a customer or see all refunded orders.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/orders/search \
  -H "Authorization: Bearer XXXX" \
  -d "customer=1055961503028478872"

Again, this returns 200 OK and an array of order information, even if this call only returns one order.

You can use multiple data fields to narrow down a search. However, each field must match exactly; otherwise, the search will return all orders.

Edit an Order

To change one or more values in a single order, use a PUT call with the orders/{ID number} endpoint. You can change most field values through this method, including changing an order from unpaid to paid status, updating the shipping address, or adding a payment gateway. You cannot add items to an order through this method. See the Add an Item to an Order section for more information on how to do that.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/orders/:id \
 -H "Authorization: Bearer XXXX"
 -d "gateway=stripe"

This returns 200 OK and the updated order information.

Add an Item to an Order

While orders do not need to contain any products, adding products to orders can help track sales and make it easier to deliver the items that customers purchase. To add products to an order, POST the ID number of the product and the total quantity to the order/{ID number}/items endpoint. This will return the order item information, not the order information.

This endpoint uses and returns the data fields shown in the table below.

Key Type Required Unique Details
order Integer/Array Yes No Links to the order that contains this item.
product Integer/Array No No The product that this order item relates to.
sku String Yes No The SKU identifier associated with this product.
title String Yes No The name of this product within the order. This can be the same as the name of the product.
quantity Integer Yes No The number of units of this product that this order item represents.
tax_rate decimal Yes No The percentage rate at which this item is taxed.
tax_band Integer/Array Yes No The tax band that represents how this item is taxed.
price decimal Yes No The price that your store charges for this item before shipping and taxes.
curl -X POST https://api.molt.in/v1/orders/1069799123244286525/items \
 -H "Authorization: Bearer XXXX" \
 -d "sku=1893015" \
 -d "title=12-cup Coffeemaker, Sale Price" \
 -d "quantity=2" \
 -d "tax_rate=3.00" \
 -d "tax_band=1018614836851901054" \
 -d "price=34.99"

On success, this returns 201 Created.

Get Order Items

To see all items in an order, call a GET request against the orders/{ID number}/items endpoint. You can paginate results using the offset and limit fields.

curl -X GET https://api.molt.in/v1/orders/:id/items \
 -H "Authorization: Bearer XXXX"

This returns 200 OK and an array of order items.

Update an Item in an Order

To update an item, use the same request as adding items to an order. This is primarily used to update quantities of items in orders, so it also uses the POST method.

curl -X POST https://api.molt.in/v1/orders/:id/items \
 -H "Authorization: Bearer XXXX" \
 -d "sku=1893015" \
 -d "title=12-cup Coffeemaker, Sale Price" \
 -d "quantity=5" \
 -d "tax_rate=3.00" \
 -d "tax_band=1018614836851901054" \
 -d "price=34.99"

Delete an Item from an Order

To remove an item from an order, use the same orders/{ID number}/items endpoint, except with the DELETE request method. This will remove the item entirely from the order. If you want to lower the quantity, use the update items method shown above.

curl -X DELETE https://api.molt.in/v1/orders/:id/items/:itemId \
 -H "Authorization: Bearer XXXX" \
 -d "sku=1893015"

Delete a Single Order

To remove an entire order, use the same orders/{ID number} endpoint we used to retrieve a single order, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/orders/:id
	-H "Authorization: Bearer XXXX"

If successful, this call returns 200 OK and the following:

{
	"status":true,
	"message":"Order removed successfully"
}