• Version: 1.2.0

Shipping

The shipping endpoint stores the various shipping and handling options available to your customers. You can have multiple shipping options based on weight, price, shipping company, or any combination of the three. You can separate them by speed, although that information is not stored in the Shipping object; you can indicate it in the description and/or title. Shipping also includes a price, which will automatically be added to the price of any [order]((/documentation/orders) that uses a shipping method.

Shipping is a flows-based structure with the following data fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the shipping method.
title String Yes No The display name for this shipping method.
slug String Yes Yes Often included in the URL for this shipping method.
company String Yes No The name of the company that provides the shipping and handling services for this method.
status Choice Yes No Whether this shipping method is live (1) or in a draft state (0).
price_min Float* No No The minimum price of an order that can use this shipping method.
price_max Float* No No The maximum price of an order that can use this shipping method. We recommend using 0 to indicate that there is no maximum value.
weight_min Float* No No The minimum weight of an order that can use this shipping method.
weight_max Float* No No The maximum weight of an order that can use this shipping method. We recommend using 0 to indicate that there is no maximum value.
tax_band [Tax]((/documentation/orders) Yes No The tax bracket associated with this shipping method.
description String No No You can enter HTML tags to format this description.
price Float* Yes No The price of shipping an order by this method.

*All Float values are limited to two decimal places.

This topic will cover the following processes:

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

Create a Shipping Method

Shipping methods are optional parts of [orders]((/documentation/orders), though they can simplify price calculation if you add charges for delivering physical products. To create a shipping method, POST the shipping data to the https://api.molt.in/v1/shipping endpoint. Shipping methods must have data for all of the required fields in the table above. You can put data fields in any order. If you do not provide one or more of the required fields, the endpoint will return a message stating which fields are missing.

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

curl -X POST https://api.molt.in/v1/shipping \
	-H "Authorization: Bearer XXXX" \
	-d "title=Standard Ground" \
	-d "slug=standard-ground" \
	-d "company=FexEx" \
	-d "status=1" \
	-d "tax_band=1038552069344068212" \
	-d "price=4.95"

On success, this call returns a 201 Created HTML status code and the shipping information for the newly created object, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
	"status":true,
	"result":
	{
		"id":"1039365874345051084",
		"order":null,
		"created_at":"2015-07-28 22:21:26",
		"updated_at":"2015-07-28 22:21:26",
		"title":"Standard Ground",
		"slug":"standard-ground",
		"company":"FexEx",
		"status":
		{
			"value":"Live",
			"data":
			{
				"key":"1",
				"value":"Live"
			}
		},
		"price_min":0,
		"price_max":0,
		"weight_min":0,
		"weight_max":0,
		"tax_band":
		{
			"value":"Electronics",
			"data":
			{
				"id":"1038552069344068212",
				"title":"Electronics",
				"description":null,
				"rate":7,
				"created_at":null,
				"updated_at":null
			}
		},
		"description":"",
		"price":
		{
			"value":"\u00a35.30",
			"data":
			{
				"formatted":
				{
					"with_tax":"\u00a35.30",
					"without_tax":"\u00a34.95",
					"tax":"\u00a30.35"
				},
				"rounded":
				{
					"with_tax":5.3,
					"without_tax":4.95,
					"tax":0.35
				},
				"raw":
				{
					"with_tax":5.2965,
					"without_tax":4.95,
					"tax":0.3465
				}
			}
		}
	}
}

Retrieve Shipping Information

Once you have created the shipping methods that affect your potential orders, you have two ways to retrieve that information. The first requires that you know the ID number of the shipping method that you want, and it returns solely the information for that one method. The second returns an array of shipping methods 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 Shipping Method by ID

You can GET shipping information by adding the specific ID number of the desired method to the shipping 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/shipping/1039365874345051084 \
	-H "Authorization: Bearer XXX"

A successful call returns a 200 OK status code and the shipping information for the selected ID number as shown in the Create a Shipping Method section.

Retrieve a List of All Shipping Methods

Using the https://api.molt.in/v1/shipping endpoint, you can return an array that contains all of the shipping methods that you have created.

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

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

On success, this returns 200 OK and an array of shipping information, as shown in the Retrieve a Single Shipping Method by ID section.

If you want to otherwise limit or affect the list of results, you can use the following options:

Key Type Details
limit Integer The maximum number of shipping methods to return.
offset Integer The number of shipping methods to skip from the beginning of the list.

Edit a Shipping Method

To change one or more values in a single shipping method, use a PUT call with the shipping method/{shipping ID} endpoint. You can change most field values through this method, including prices, minimum and maximums, or live status.

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

curl -X PUT https://api.molt.in/v1/shipping/:id \
	-H "Authorization: Bearer XXXX" \
	-d "price_min=50.00"

On success, this returns 200 OK and the updated shipping information.

Delete a Single Shipping Method

To remove a shipping method, you use the same shipping method/{ID number} endpoint we used to retrieve a single method, except we use the DELETE request.

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

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

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

{
	"status":true,
	"message":"Shipping method removed successfully"
}