Introduction

moltin is the the headless commerce API that puts the power in your hands.

The moltin API is designed around REST and you must sign up for an API key before you can make requests.

The JavaScript code examples in this API reference use the official moltin JavaScript SDK.

If you have any questions on how to use, improve or show off what you're building with moltin, our community forum is the place to be.

Authentication

All requests to the API need to be accompanied by an authorisation header with a authentication token:

Authorization: Bearer 212LJ3k0i2382364HIUEjfeJB98yvH

Authentication tokens are generated via the authentication endpoint.

The authentication object

There are two main token types available for use within your store client_credentials and implicit. The implicit token is the more limited of the two, restricting access to mostly read-only whereas client_credentials has full read and write access.

Create an implicit token

An implicit token is typically used for situations where you are requesting data on the client side and you are exposing your public key, NOT your private key - such as JavaScript.

implicit tokens can only read and write to specific endpoints.

HTTP Request

POST/oauth/access_token

Request Body

Attribute

Type

Description

client_id

string

Your client_id.

grant_type

string

The grant type, in this case it must be client_credentials.

Which access token should I use?

There are two main token types available for use within your store client_credentials and implicit.

The implicit token is the more limited of the two, restricting access to mostly read-only whereas client_credentials has full access to read and write.

Client Credentials

A breakdown of the access given by the token can be seen in the following table.

Endpoints

Read access

Write access

/brands

✔

✔

/carts

✔

✔

/categories

✔

✔

/checkout

✔

✔

/collections

✔

✔

/currencies

✔

✔

/customers

✔

✔

/files

✔

✔

/flows

✔

✔

/integrations

✔

✔

/orders

✔

✔

/payment-gateways

✔

✔

/products

✔

✔

/promotions

✔

✔

/settings

✔

✔

Implicit

The table below shows a breakdown of which API endpoint actions are available to this token type.

Endpoints

Read access

Write access

/brands

✔

✕

/carts

✔

✔

/categories

✔

✕

/checkout

✔

✔

/collections

✔

✕

/currencies

✔

✕

/customers

✕

✕

/files

✔

✕

/flows

✔

✕

/integrations

✕

✕

/orders

✕

✕

/payment-gateways

✕

✕

/products

✔

✕

/promotions

✕

✕

/settings

✕

✕

Filtering

You can make API (GET) requests which filter the results that are returned using a standard URI format.

Filtering is available on a number of API endpoints (but not all). We currently support eq (equals), like (like), gt (greater than), ge (greater than or equal to),
lt (less than) and le (less than or equal to) operators.

The operators that are available to filter by depends on the attribute type. Each section of the documentation has filtering information to help you identify how to filter those resources.

This endpoint allows updates of the prescribed settings. Sparse updates are allowed, meaning you do not have to set every property (type is required!) - you can set just page_length if that is the only setting you wish
to change.

There is a limit on the number of translations allowed in the system. It is currently set to 5.

Supported Languages

Below is a list of supported languages - the system only deals with the alpha2 language codes presently.

Name

Code

Abkhazian

ab

Afrikaans

af

Albanian

sq

Armenian

hy

Avaric

av

Avestan

ae

Aymara

ay

Azerbaijani

az

Basque

eu

Belarusian

be

Bosnian

bs

Bulgarian

bg

Catalan; Valencian

ca

Corsican

co

Czech

cs

Danish

da

Dutch; Flemish

nl

English

en

Estonian

et

Fijian

fj

Finnish

fi

French

fr

German

de

Gaelic; Scottish Gaelic

gd

Irish

ga

Greek, Modern

el

Haitian; Haitian Creole

ht

Croatian

hr

Hungarian

hu

Icelandic

is

Italian

it

Latvian

lv

Lithuanian

lt

Luxembourgish; Letzeburgesch

lb

Norwegian

no

Persian

fa

Polish

pl

Portuguese

pt

Romanian; Moldavian; Moldovan

ro

Russian

ru

Slovak

sk

Slovenian

sl

Samoan

sm

Spanish; Castilian

es

Sardinian

sc

Serbian

sr

Swedish

sv

Ukrainian

uk

Welsh

cy

```

Addresses

This feature is currently in beta and is subject to change. Exercise caution when using in production

Request Body

Carts

Carts contain the products and custom items that a customer will purchase, it's a storage space for your customers purchases prior to checkout, like a shopping basket.

When a customer is ready to purchase the items in their cart, you can convert their cart into an order using the checkout endpoint. After checking out, the cart will still exist so if your customer decides to make a change, you can modify the
cart contents and checkout again.

Carts live for 7 days after they were last modified. Once a cart hasn't been updated for 7 days, it is automatically removed from the system.

When you add a product to a cart, a snapshot of that product is saved as a cart_item.custom_items and promotion_items are other examples of cart_items.

Attribute

Type

Description

id

string

The unique identifier for this cart

type

string

The type of item in the cart. This can be a cart_item or custom_item.

name

string

Denotes the name of this item

description

string

A description of the cart item

sku

string

The SKU code for the item

quantity

integer

How many of this item have been added to the cart

unit_price

object

Contains pricing information about a single instance of this item

unit_price.amount

integer

The singular price of this item as an integer

unit_price.currency

string

The currency this item was added to the cart as

unit_price.includes_tax

boolean

Whether or not this price is tax inclusive

value

object

Contains pricing information total value of this item line based on the quantity

value.amount

integer

The total price for this item line (quantity * unit_price.amount)

value.currency

string

The currency this item was added to the cart as

value.includes_tax

boolean

Whether or not this price is tax inclusive

links

object

A collection of URLs related to this resource

links.product

string

A link to the product this cart item is a snapshot of Not present for custom items

meta

object

Additional information calculated for this cart

meta.display_price

object

A collection of fields related to the totals and currency of this cart item

meta.display_price.with_tax

object

Tax inclusive totals

meta.display_price.with_tax.unit

object

Tax inclusive totals for a single instance of this cart item

meta.display_price.with_tax.unit.amount

integer

The raw price of a single instance this cart item (inc tax)

meta.display_price.with_tax.unit.currency

string

The currency set for this cart item

meta.display_price.with_tax.unit.formatted

string

The tax inclusive formatted total of a single instance of this cart item based on the currency

meta.display_price.with_tax.value

object

Tax inclusive totals for this cart item based on the quantity

meta.display_price.with_tax.value.amount

integer

The raw total price this cart item line (inc tax)

meta.display_price.with_tax.value.currency

string

The currency set for this cart item

meta.display_price.with_tax.value.formatted

string

The tax inclusive formatted total of this cart item line based on the currency

meta.display_price.without_tax

object

Tax exclusive totals

meta.display_price.without_tax.unit

object

Tax exclusive totals for a single instance of this cart item

meta.display_price.without_tax.unit.amount

integer

The raw price of a single instance this cart item (ex tax)

meta.display_price.without_tax.unit.currency

string

The currency set for this cart item

meta.display_price.without_tax.unit.formatted

string

The tax exclusive formatted total of a single instance of this cart item based on the currency

meta.display_price.without_tax.value

object

Tax exclusive totals for this cart item based on the quantity

meta.display_price.without_tax.value.amount

integer

The raw total price this cart item line (ex tax)

meta.display_price.without_tax.value.currency

string

The currency set for this cart item

meta.display_price.without_tax.value.formatted

string

The tax exclusive formatted total of this cart item line based on the currency

meta.timestamps

object

Timestamps for this cart item

meta.timestamps.created_at

string

The creation date of this cart item

meta.timestamps.updated_at

string

The last updated date of this cart item

Interacting with a cart

Any request that adds, updates or deletes items from a cart will return a response containing a collection of Cart Item Objects.

One point of note here, for consumers of these requests, is the inclusion within the meta data of the response of the messages property. This property details other actions that have occurred that are a result of the target request
being successful.

By way of an example, should any change made to the cart items invalidate a promotion and that promotion were removed from the cart then this would be indicated within this messages property.

The most common type of item you'll add to a cart; a cart_item is a product which exists in your store's inventory, having been previously added to your store. Most stores will use cart_items for all of their
add to cart requests.

HTTP Request

POST/v2/carts/{CART_REFERENCE}/items

Headers

Header

Type

Description

Authorization

string

The Bearer token to grant access to the API. required

URL Parameters

URL Param

Type

Description

cart_reference

string

A custom reference for this cart generated by you

Request Body

Attribute

Type

Description

data

object

Contains the request information

id

string

The ID of the product to be added to the cart

type

string

The type of item to add to the cart. In this case it must be cart_item

A custom_item is an arbitrary item that isn't an existing piece of store inventory. It has no relevance outside of the cart it was added to.custom_items are useful for stores that want to calculate things such
as tax, shipping or surcharges just before checkout.

HTTP Request

POST/v2/carts/{CART_REFERENCE}/items

Headers

Header

Type

Description

Authorization

string

The Bearer token to grant access to the API. required

URL Parameters

URL Param

Type

Description

cart_reference

string

A custom reference for this cart generated by you

Request Body

Attribute

Type

Description

data

object

Contains the request information

type

string

The type of item to add to the cart. In this case it must be custom_item

HTTP Request

URL Parameters

Request Body

Attribute

Type

Description

data

array[object]

data[].type

string

The type of related object (should be category)

data[].id

string

The id of the child category

Checkout

Once you are ready to checkout, you can convert your cart to an order. The original cart will remain and can be modified and checked out again if required. The new order will be returned and data.meta.payment_gateways will contain
an array of the available payment gateways for this order.

Using a customer ID

Checkout a cart and create a new order with an associated customer ID.

A flow describes a collection of fields. It is named after the internal entity type you wish to associate it with. For example a flow with a slug of products will be applied to all product responses in your store.

A field represents a single field of data (for example a Product Rating) to be applied to an entity. All fields have a type (string, integer, boolean or date), a default value and
an optional set of validation rules.

An entry is a specific instance of a flow and is associated with a specific instance of an entity (for example, a single product).

URL Parameters

Flow Field Validation Rules

When creating a flow field, you can add validation to values that are stored. The validation you can use depends on the field_type and each one is expressed as a validation rule object:

string / enum

{
"type": "enum",
"options": [
"fast",
"slow"
]
}

Must be one of a predefined collection of strings.

Attribute

Type

Description

type

string

enum

options

array[string]

An array of valid string values.

string / email

{
"type": "email"
}

Must be a valid email address.

Attribute

Type

Description

type

string

email

string / slug

{
"type": "slug"
}

Can contain only letters, numbers, hyphens & underscores.

Attribute

Type

Description

type

string

slug

integer / between

{
"type": "between",
"options": {
"from": 1,
"to": 5
}
}

Must be between the two provided values.

Attribute

Type

Description

type

string

enum

options

object

an object containing from and to integers.

integer / enum

{
"type": "enum",
"options": [
1,
2,
3,
4,
5
]
}

Must be one of a predefined collection of integers.

Attribute

Type

Description

type

string

enum

options

array[integer]

an array of valid integer values.

float / between

{
"type": "between",
"options": {
"from": 0.0,
"to": 5.0
}
}

Must be between the two provided values.

Attribute

Type

Description

type

string

enum

options

object

an object containing from and to floats.

float / enum

{
"type": "enum",
"options": [
0.0,
0.5,
1.0
]
}

Must be one of a predefined collection of floats.

Attribute

Type

Description

type

string

enum

options

array[float]

an array of valid float values.

date / enum

{
"type": "enum",
"options": [
"2017-12-25",
"2017-12-26"
]
}

Must be one of a predefined collection of dates.

Attribute

Type

Description

type

string

enum

options

array[string]

an array of valid date values as strings (YYYY-MM-DD HH:MM:SS - time is optional).

Integrations

Integrations allow you to receive notifications to when events you select to observe happen on your store. This allows you to handle any custom processes that you need to run when activity occurs within the your
store.

To see which events you can be notified about, please review the observes field in the Integration model.

When an observable event occurs, we will attempt to deliver that to your integration based on it's type and configuration.

There are two types of integrations: webhook and email.

When delivering a webhook and we receive a reponse with a Status Code in the 2xx range, we will consider that notification delivered. If the status code is outside of that range then we treat the job as failed.

When delivering an email over SMTP, if we receive a non OK status (ie not 250) then we will attempt a redelivery as per the retry policy (see below).

Configuration object

A configuration object is used on an integration so that the when the integration fires, we can properly notify you of the event. You should use the corresponding configuration for your integrations integration_type.

Webhook Configuration

When we deliver a webhook we will send a POST request to the configured url. If you have added a secret_key we will add a header to the request called X-MOLTIN-SECRET-KEY. This allows you to verify that the request originated from us.

We will also add a X-MOLTIN-INTEGRATION-TRIGGER header which allows you to process several integrations from the same endpoint. The value of this header will be the observed event (e.g. order.created, product.deleted).

Attribute

Type

Description

url

string

A fully qualified URL to notify of the event. required

secret_key

string

When supplied, the notification from our system to yours will contain a header (X-MOLTIN-SECRET-KEY with this value so you can verify it originates from moltin). optional

The body of the email will be created depending on the configuration. You can send plaintext or HTML emails.

If you would like more control over the email you can instead add a body_url. If this is present we will make a POST request with a payload (see below) and an optional body_secret_key which adds a X-MOLTIN-SECRET-KEY so you can verify the call
originated from us.

Using the body_url is very powerful - you can use it to include data from your own systems or even make calls to moltin to get additional content (such as products in a category) to add to the body.

Your server must return a string as response and generating the email body this way is subject to the same delivery retry interval as a webhook. If you cannot generate the body in time (30 seconds) then the request will time out and the operation
to send an email cancelled.

Observable events

Integrations can be triggered when the following events occur on your store. You can use any number of these keys in the observes field of the integration object or can split them out across integrations
to perform different actions when different events occur on your store:

The payload (delivered to a URL of your choosing - url for webhook configurations or email_body_url for email configurations - will contain a payload with information about the event that has been triggered.

Responding to Integrations

We do not require a response from a webhook unless it is part of an email. If you are generating dynamic content for your email, you must respond with JSON.

We will use the values received from your server to deliver the email with. Note that you can set proceed to false if you want to cancel the email being sent. A true value will mean that we continue processing the integration
and attempt delivery of the email.

If for any of the fields inside the email object are empty, we will use the value from the integration itself.

URL Parameters

Inventory

This feature is currently in beta and is subject to change. Exercise caution when using in production

Your inventory is the place where your stock is managed. Each Product in your catalogue has corresponding stock. For convenience, when you create a product, you can optionally send in an initial stock level (which otherwise defaults
to 0).

Each stocked product can have transactions applied to it so that the movement of your stock can be audited.

The stock object

The stock object represents the stock levels for a given product in moltin.

Get order items

HTTP Request

Headers

Header

Type

Description

Authorization

string

The Bearer token to grant access to the API. required

URL Parameters

URL Param

Type

Description

order_id

string

The id for the order requested.

Paying for an order

After checking out a cart, you'll have an unpaid order. How you pay for the order depends on the payment gateway & method you'd like to use. Moltin supports a number of payment gateways and we're adding new ones all the time!

Payment methods

We support a number of different payment methods which allow you to capture funds immediately, or authorize them to be captured later. Some methods may or may not be available to you depending on your chosen gateway.

Purchase

Purchase is the simplest method of capturing a payment. The gateway will attempt to charge the customer immediately and the result of the attempt will be returned.

Authorize

Many stores choose to authorize a payment so that the funds can be captured at a later date such as when an item is dispatched, or when it comes into stock.

Capture

Once you have an authorized transaction, you can use the capture method to capture the authorized funds.

Capture an authorized payment

Once you've authorized a payment, you'll want to be able to capture those funds. This is as simple as a single POST request.

Braintree Payments

With all Braintree endpoints, you may pass an options object containing a custom_fields object with any custom fields you have configured in Braintree. Braintree will reject any request containing custom fields that have not been set up in the
Braintree admin area.

Card Payment

This request allows you to pay for an order using Braintree and a users credit card.

HTTP Request

URL Parameters

Request Body

Attribute

Type

Description

type

string

Represents the type of object (should be variation)

id

string

The id of the variation

Product Variations

Variations allow you to create the variations that your products have. Things like size or colour are examples of a variation. Using this system you can reliably create all possible combinations of your product.

The variation object is delivered as a compound document (it includes the attached options and modifiers). This is because the options and modifiers that constitue the variation are integral to its function and have no relevance in any other context.

Build child products

This endpoint builds your child/variation products. Once you have a base product and have attached some variations, this endpoint will trigger the process that applies those variations to the base product. The result will be a list of child products
that each have one combination of the variation options applied to it. The product_id you should use in the url is that of the base product.

HTTP Request

POST/v2/products/{PRODUCT_ID}/build

URL Parameters

URL Param

Type

Description

product_id

string

The id of the base product to be built

HTTP Headers

Attribute

Type

Description

X-MOLTIN-CURRENCY

string

ISO code of the required currency

Product Variation Options

Variation options allow for the assignment of the different options associated with a variation.

Delete a Product Variation Option

Use this endpoint to delete an existing product variation option you no longer need.

HTTP Request

DELETE/v2/variations/{VARIATION_ID}/option/{OPTION_ID}

URL Parameters

URL Param

Type

Description

variation_id

string

The id of the variation belonging to the option

option_id

string

The id of the option to be deleted

Product Modifiers

Product modifiers create the variation products (child products) from your base product by augmenting different properties of that base product. In each case you will specify a modifier type and its value, this will define in what way that property
changes as the child products are built.

There is currently a limit on the number of child products you can build from a base product. This limit is currently set at 200. This means the maximum number of child products generated from base product cannot exceed this figure.

Price Modifiers: These obviously help adjust the price of a product. Since this kind of modifier deals with prices, it should come as no surprise to you that the value of this modifier must be a collection of
currency values similar to that when specifying a product price. While the modifier can have any number of currencies applied to it, only the currencies specified on the actual base product will be subjected to any modifiers. ie. If you have
USD and GBP values on a base product and apply a modifier that alters GBP, AUD and EUR the ONLY currency value affected will be GBP, the USD value will remain the same and no other currencies will be set on the variation product.

SKU Builder Modifiers: These modifiers can help you fulfil a robust SKU and slug strategy. The value of the modifier must contain two property-value pairs: "seek": "XXX" and "set" : "YYY".
In order for this kind of modifier to participate in the variation products building process, the base product should have a SKU set with a place holder like: {XXX}. The modifer works by replacing the placehodler with the value
you wish to set. You should only specify the contents of the { } in the seek property - the modifier will take care of the rest.

Promotions

This feature is currently in beta and is subject to change. Exercise caution when using in production

Promotions allow you to provide discounts to customers. By defining a promotion, and a code, you put in place the facility to offer discounts to customers, applied directly to their shopping carts.

The promotions you create will require codes to be attached to them, and these codes are subsequently used by end-users (or your own system) to apply promotions to carts and provide the discounts stipulated.

The start time of the promotion DateTime yyyy-mm-dd, yyyy-mm-ddThh:mm:ss+hh::mm The simpler format wil start the promotion at 00:00 UTC of the date specified.

end

string

The end time of the promotion DateTime yyyy-mm-dd, yyyy-mm-ddThh:mm:ss+hh::mm, The simpler format wil end the promotion at 00:00 UTC of the date specified.

You can re-enable an expired promotion by updating the end date and setting it in the future, in doing so you will clear out any previously attached codes - this is part of the system that prevents duplicate promotion codes existing on different
promotions.