Introduction

API endpoint

https://api.moltin.com

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.

{
  "expires": 1500638876,
  "identifier": "client_credentials",
  "expires_in": 3600,
  "access_token": "232405fa7d09c11f736aacf3f5d0e34ddd340b14",
  "token_type": "Bearer"
}
Attribute Type Description
expires timestamp The epoch time that this token expires at.
identifier string The type of token requested. This can be a client_credentials or implicit.
expires_in integer The duration in seconds in which the token will expire.
access_token string The access token you will use for subsequent authenticated requests to additional endpoints.
token_type string The type of token you are receiving. This will only be Bearer right now.

Create a client credential token

curl -X "POST" "https://api.moltin.com/oauth/access_token" \
  -d "client_id=XXXX" \
  -d "client_secret=XXXX" \
  -d "grant_type=client_credentials"
const Moltin = MoltinGateway({
  client_id: "XXXX",
  client_secret: "XXXX"
});

A client_credentials token is used when the credentials are not publicly exposed, usually a server side language such as PHP or nodeJS.

HTTP Request

POST /oauth/access_token

Request Body

Attribute Type Description
client_id string Your client_id.
client_secret string Your client_secret.
grant_type string The grant type, in this case it must be client_credentials.

Create an implicit token

curl -X "POST" "https://api.moltin.com/oauth/access_token" \
  -d "client_id=XXXX" \
  -d "grant_type=implicit"
const Moltin = MoltinGateway({
  client_id: "XXXX"
});

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.

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.

Example Usage

eq:

To get all digital products in a catalogue, we can make a call to:

GET https://api.moltin.com/v2/products?filter=eq(commodity_type,digital)

like:

To get all products whose SKU begins with the phrase SHOE_DECK_:

GET https://api.moltin.com/v2/products?filter=like(sku,SHOE_DECK_*)

To get all products whose SKU contains with the phrase _DECK_:

GET https://api.moltin.com/v2/products?filter=like(sku,*_DECK_*)

To get all products whose SKU ends with the phrase _RED:

GET https://api.moltin.com/v2/products?filter=like(sku,*_RED)

Available Resource Filtering

We support filtering on the following resources:

Settings

The settings service allows you to configure aspects of your store.

The settings object

{
  "data": {
    "type": "settings",
    "page_length": 100,
    "list_child_products": true,
    "additional_languages": ["es","fr"]
  }
}
Name Type Description
type string "settings"
page_length integer the number of records per page when paginating results (current max 100)
list_child_products boolean display child products in product listings (default true) see variations
additional_languaes array array of language codes that can be defined on a store - codes should conform to IETF language tag standards (defaults to [] - an empty array)

Get Settings

curl -X GET https://api.moltin.com/v2/settings \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"

The response will be a settings object.

HTTP Request

GET /v2/settings

Update Settings

curl -X PUT https://api.moltin.com/v2/settings \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
"data": {
  "type": "settings",
  "page_length": 70,
  "list_child_products": false,
  "additional_languages": ["es","fr","de","pr-BR"]
}
}'

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.

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

The address object

The address object is a representation of an address in moltin.

{
  "data": {
    "id": "4d49d427-ec5f-4acf-99b5-cf7b8194d31d",
    "type": "address",
    "first_name": "Ron",
    "last_name": "Swanson",
    "name": "Home",
    "instructions": "Leave behind the bins",
    "company_name": "Ron Swanson Enterprises",
    "line_1": "1 Sunny Street",
    "line_2": "Sunny Place",
    "city": "Sunny Town",
    "county": "Sunnyville",
    "postcode": "SU33 1YY",
    "country": "GB"
  }
}
Attribute Type Description
id string The unique identifier for this address.
type string Represents the type of object being returned. required
first_name string The first name of the recipient on this address. required
last_name string The last name of the recipient on this address. required
name string The name under which this address is saved. You can display this name to the customer when you ask them to select from their saved addresses. required
instructions string Any delivery instructions for this address. required
company_name string The company name at this address. required
line_1 string The first portion of the address, usually the street address. required
line_2 string The second portion of the address, usually an apartment or unit number. required
city string The city for this address. required
county string The county for this address. required
postcode string The ZIP Code, Postcode, or other postal reference string for this delivery address. required
country string A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard. required

Get a list of addresses

Get a list of all addresses

curl -X GET https://api.moltin.com/v2/customers/{CUSTOMER_ID}/addresses \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/customers/{CUSTOMER_ID}/addresses

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer addresses for implicit calls. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer you are requesting addresses for.

Get an address

Get a single address by id.

curl -X GET https://api.moltin.com/v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer addresses for implicit calls. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer you are requesting addresses for.
address_id string The id for the address requested.

Create an address

Create a new address.

curl -X POST https://api.moltin.com/v2/customers/{CUSTOMER_ID}/addresses \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "address",
    "first_name": "Ron",
    "last_name": "Swanson",
    "name": "Home",
    "instructions": "Leave behind the bins",
    "company_name": "Ron Swanson Enterprises",
    "line_1": "1 Sunny Street",
    "line_2": "",
    "city": "Sunny Town",
    "county": "Sunnyville",
    "postcode": "SU33 1YY",
    "country": "GB"
  }
}'
Not supported yet

HTTP Request

POST /v2/customers/{CUSTOMER_ID}/addresses

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer addresses for implicit calls. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer you are requesting addresses for.

Request Body

Attribute Type Description
type string Represents the type of object being returned. optional
first_name string The first name of the recipient on this address. optional
last_name string The last name of the recipient on this address. optional
name string The name under which this address is saved. You can display this name to the customer when you ask them to select from their saved addresses. optional
instructions string Any delivery instructions for this address. optional
company_name string The company name at this address. optional
line_1 string The first portion of the address, usually the street address. optional
line_2 string The second portion of the address, usually an apartment or unit number. optional
city string The city for this address. optional
county string The county for this address. optional
postcode string The ZIP Code, Postcode, or other postal reference string for this delivery address. optional
country string A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard. optional

Update an address

Update an existing address

curl -X PUT https://api.moltin.com/v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID} \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "id": "{ADDRESS_ID}",
        "type": "address",
        "name": "Office"
    }
}'
Not supported yet

HTTP Request

PUT /v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer addresses for implicit calls. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer you are requesting addresses for.
address_id string The id for the address requested.

Request Body

Attribute Type Description
id string The unique identifier for this address. required
type string Represents the type of object being returned. required
first_name string The first name of the recipient on this address. optional
last_name string The last name of the recipient on this address. optional
name string The name under which this address is saved. You can display this name to the customer when you ask them to select from their saved addresses. optional
instructions string Any delivery instructions for this address. optional
company_name string The company name at this address. optional
line_1 string The first portion of the address, usually the street address. optional
line_2 string The second portion of the address, usually an apartment or unit number. optional
city string The city for this address. optional
county string The county for this address. optional
postcode string The ZIP Code, Postcode, or other postal reference string for this delivery address. optional
country string A two digit code for the country this address is in, expressed as per the ISO 3166-2 standard. optional

Delete an address

Delete an address by id.

curl -X DELETE https://api.moltin.com/v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/customers/{CUSTOMER_ID}/addresses/{ADDRESS_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer addresses for implicit calls. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer you are requesting addresses for.
address_id string The id for the address to be deleted.

Brands

Brands allow you to organize your products into hierarchical groups. Where a shoe product might be in the category Shoes, the individual product might also be in the brand Nike.

The brand object

{
  "data": {
    "id": "9185d4ff-a484-408b-8c1a-d4de1ca20736",
    "type": "brand",
    "name": "Cool Clothing",
    "slug": "cool-clothing",
    "description": "Cool clothing make cool clothes!",
    "status": "live"
  }
}
Attribute Type Description
id string The unique identifier for this brand.
type string Represents the type of object being returned. required
name string The name of the brand. required
slug string A unique slug identifier for the brand. required
description string Any description for this brand. required
status string live or draft depending on the brand status. required

Brand filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
name string eq, like eq(name,'Nike')
slug string eq, like like(name,'ni*')
status boolean eq eq(status,live)

Get a list of brands

Get a list of all brands.

curl -X GET https://api.moltin.com/v2/brands \
     -H "Authorization: Bearer XXXX"
Moltin.Brands.All().then((brands) => {
    // Do something
});

HTTP Request

GET /v2/brands

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Query String

Attribute Type Description
filter string Filter the results
include string brands, products

Get a brand

Get a single brand by id.

curl -X GET https://api.moltin.com/v2/brands/{BRAND_ID} \
     -H "Authorization: Bearer XXXX"
Moltin.Brands.Get('{BRAND_ID}').then((brand) => {
    // Do something
});

HTTP Request

GET /v2/brands/{BRAND_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
brand_id string The id for the brand requested.

Get the brands tree

Get a tree view of your brands.

curl -X GET https://api.moltin.com/v2/brands/tree \
     -H "Authorization: Bearer XXXX"
Moltin.Brands.Tree().then((brands) => {
    // Do something
});

HTTP Request

GET /v2/brands/tree

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Create a brand

Create a new brand.

curl -X POST https://api.moltin.com/v2/brands \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "brand",
        "name": "Cool Clothing",
        "slug": "cool-clothing",
        "description": "Cool clothing make cool clothes!",
        "status": "live"
     }
}'
var brand = {
    name: "Cool Clothing",
    slug: "cool-clothing",
    description: "Cool clothing make cool clothes!",
    status: "live"
}

Moltin.Brands.Create(brand).then((response) => {
  // Do something
});

HTTP Request

POST /v2/brands

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the brand. required
slug string A unique slug identifier for the brand. required
description string Any description for this brand. optional
status string live or draft depending on the brand status (defaults to draft). optional

Update a brand

Update an existing brand.

curl -X PUT https://api.moltin.com/v2/brands/{BRAND_ID} \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "brand",
        "id": "{BRAND_ID}",
        "name": "Coolest Clothing",
        "slug": "coolest-clothing",
        "description": "Cooler clothing make even cooler clothes!",
        "status": "live"
     }
}'
var brand = {
    name: "Coolest Clothing",
    slug: "coolest-clothing",
    description: "Cooler clothing make even cooler clothes!",
    status: "live"
}

Moltin.Brands.Update('{BRAND_ID}', brand).then((response) => {
  // Do something
});

HTTP Request

PUT /v2/brands/{BRAND_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
brand_id string The id for the brand to update.

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the brand. optional
slug string A unique slug identifier for the brand. optional
description string Any description for this brand. optional
status string live or draft depending on the brand status. optional

Delete a brand

Delete a brand by id.

curl -X DELETE https://api.moltin.com/v2/brands/{BRAND_ID}  \
    -H "Authorization: Bearer XXXX"
Moltin.Brands.Delete('{BRAND_ID}').then((response) => {
  // Do something
});

HTTP Request

DELETE /v2/brands/{BRAND_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
brand_id string The id for the brand to delete.

Brand Relationships

{
    "data": [{
        "type": "brand",
        "id": "9185d4ff-a484-408b-8c1a-d4de1ca20736",
        "name": "Cool Shoes",
        "status": "live",
        "slug": "cool-shoes",
        "description": "Our main shoes brand",
        "children": [
            {
                "type": "brand",
                "id": "c902aea9-ec90-4fdd-8084-3c2d879a2c52",
                "name": "MixiMax",
                "status": "live",
                "slug": "miximax",
                "description": "MixiMax brand"
            },
            {
                "type": "brand",
                "id": "43b70fc1-ed2f-45e0-b9e1-212b5e95e809",
                "name": "AirPair",
                "status": "live",
                "slug": "airpair",
                "description": "AirPair brand"
            }
        ]
    }]
}

Relationships between brands allow you to establish a hierarchical tree structure between parents and children which can be useful for organising your catalogue into logical paths.

Consider the structure on the right (which you would use the brand tree endpoint to retrieve).

The Cool Shoes brand has two children (MixiMax and AirPair).

Cool Shoes is therefore, by definition, the parent of MixiMax and AirPair.

If you were to lay these out in a dynamic website, you would most likely have three pages:

Page Name URI Brand ID
Cool Shoes /cool-shoes 9185d4ff-a484-408b-8c1a-d4de1ca20736
MixiMax /cool-shoes/miximax c902aea9-ec90-4fdd-8084-3c2d879a2c52
AirPair /cool-shoes/airpair 43b70fc1-ed2f-45e0-b9e1-212b5e95e809

We use the parent /child(ren) analogy in the relationships between brands to other brands.

Create Brand Relationships

Create a relationship to one or more other brand. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/brands \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
      "parent": {
        "type": "brand",
        "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
      },
      "children": [
        {
          "type": "brand",
          "id": "1334e667-7b2b-4159-9e36-8a3b404901c8"
        }
      ]
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/brands/{BRAND_ID}/relationships/brands

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to make relationships to

Request Body

Attribute Type Description
parent object
parent.type string The type of related object (should be brand)
parent.id string The id of the brand
children array[object]
children[].type string The type of related object (should be brand)
children[].id string The id of the brand

Create Parent Brand Relationship

Create a relationship to a parent brand. If a relationships already exists, the one from the request will overwrite it.

curl -X "POST" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "brand",
    "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
  }
}'
// Not supported

HTTP Request

POST /v2/brands/{BRAND_ID}/relationships/parent

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be brand)
id string The id of the parent brand

Update Parent Brand Relationship

Change the parent of a brand.

curl -X "PUT" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "brand",
    "id": "c902aea9-ec90-4fdd-8084-3c2d879a2c52"
  }
}'
// Not supported

HTTP Request

PUT /v2/brands/{BRAND_ID}/relationships/parent

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to update relationships to

Request Body

Attribute Type Description
type string The type of related object (should be brand)
id string The id of the new parent brand

Delete Parent Brand Relationship

Delete the parent of a brand.

curl -X "DELETE" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX"
}'
// Not supported

HTTP Request

DELETE /v2/brands/{BRAND_ID}/relationships/parent

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to update relationships to

Create Child Brand Relationships

Create a relationship to a parent brand. If any relationship(s) already exists, new ones will be added to them.

curl -X "POST" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/brands/{BRAND_ID}/relationships/children

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be brand)
id string The id of the parent brand

Update Child Brand Relationship

Update the children brand. If any relationship(s) already exists, they will be removed.

curl -X "PUT" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "c902aea9-ec90-4fdd-8084-3c2d879a2c52"
    }
  ]
}'
// Not supported

HTTP Request

PUT /v2/brands/{BRAND_ID}/relationships/children

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be brand)
id string The id of the parent brand

Delete Child Brand Relationship

Delete child brands of a brand.

curl -X "DELETE" https://api.moltin.com/v2/brands/{BRAND_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "c902aea9-ec90-4fdd-8084-3c2d879a2c52"
    }
  ]
}'
// Not supported

HTTP Request

DELETE /v2/brands/{BRAND_ID}/relationships/parent

URL Parameters

URL Param Type Description
brand_id string The id of the brand you wish to update relationships to

Request Body

Attribute Type Description
data array[object]
data[].type string The type of related object (should be brand)
data[].id string The id of the child brand

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.

The cart object

{
    "data": {
        "id": "3333",
        "type": "cart",
        "links": {
            "self": "https://api.moltin.com/v2/carts/3333"
        },
        "meta": {
            "display_price": {
            "with_tax": {
                "amount": 5891,
                "currency": "USD",
                "formatted": "$58.91"
            },
            "without_tax": {
                "amount": 5891,
                "currency": "USD",
                "formatted": "$58.91"
            }
            },
            "timestamps": {
            "created_at": "0001-01-01T00:00:00Z",
            "updated_at": "0001-01-01T00:00:00Z"
            }
        }
    }
}

A cart object is a representation of the current state of your shopping basket.

Attribute Type Description
id string The unique identifier for this cart
type string Represents the type of object being returned
links object A collection of URLs related to this resource
links.self string The URL of this cart
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
meta.display_price.
with_tax
object Tax inclusive totals
meta.display_price.
with_tax.amount
integer The raw total of this cart (inc tax)
meta.display_price.
with_tax.currency
string The currency set for this cart
meta.display_price.
with_tax.formatted
string The tax inclusive formatted total based on the currency
meta.display_price.
without_tax
object Tax exclusive totals
meta.display_price.
without_tax.amount
integer The raw total of this cart (ex tax)
meta.display_price.
without_tax.currency
string The currency set for this cart
meta.display_price.
without_tax.formatted
string The tax exclusive formatted total based on the currency
meta.timestamps object Timestamps for this cart
meta.timestamps.
created_at
string The creation date of this cart
meta.timestamps.
updated_at
string The last updated date of this cart

The cart item object

{
    "data": {
        "id": "6aa9580e-3a27-49fb-8af3-3b93a71add91",
        "type": "cart_item",
        "product_id": "df32387b-6ce6-4802-9b90-1126a5c5a54f",
        "name": "Deck Shoe",
        "description": "Modern boat shoes were invented in 1935 by American Paul A. Sperry of New Haven, Connecticut after noticing his dog's ability to run easily over ice without slipping. Using a knife, he cut siping into his shoes' soles, inspiring a shoe perfect for boating and a company called Sperry Top-Sider.",
        "sku": "DS.001",
        "quantity": 1,
        "unit_price": {
            "amount": 8950,
            "currency": "GBP",
            "includes_tax": true
        },
        "value": {
            "amount": 8950,
            "currency": "GBP",
            "includes_tax": true
        },
        "links": {
            "product": "https://api.moltin.com/v2/products/df32387b-6ce6-4802-9b90-1126a5c5a54f"
        },
        "meta": {
            "display_price": {
                "with_tax": {
                    "unit": {
                        "amount": 8950,
                        "currency": "GBP",
                        "formatted": "£89.50"
                    },
                    "value": {
                        "amount": 8950,
                        "currency": "GBP",
                        "formatted": "£89.50"
                    }
                },
                "without_tax": {
                    "unit": {
                        "amount": 8950,
                        "currency": "GBP",
                        "formatted": "£89.50"
                    },
                    "value": {
                        "amount": 8950,
                        "currency": "GBP",
                        "formatted": "£89.50"
                    }
                }
            },
        "timestamps": {
            "created_at": "2017-10-25T14:08:28.569Z",
            "updated_at": "2017-10-25T14:08:28.569Z"
        }
    }
}

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.

{
    ...,
    "meta": {
        ...,
        "messages": [
            {
                "source": {
                    "type": "promotion_item",
                    "id": "331ef28f-d0d5-4746-b7f1-01182c80787c"
                },
                "title": "Deleted Promotion",
                "description": "Promotion has been removed."
            }
        ]
    }
}

While this is purely information, it may be useful in keeping customers updated on changes in their shopping carts.

Add a product to a cart

curl -X POST https://api.moltin.com/v2/carts/{CART_REFERENCE}/items \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
"data": {
    "id": "df32387b-6ce6-4802-9b90-1126a5c5a54f",
    "type": "cart_item",
    "quantity": 1
  }
}'
Moltin.Cart("{CART_REFERENCE}").AddProduct("df32387b-6ce6-4802-9b90-1126a5c5a54f", 1).then((cart) => {
  // Do something
});

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
quantity integer How many of this item to add to the cart

Add a custom item to a cart

curl -X POST https://api.moltin.com/v2/carts/{CART_REFERENCE}/items \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "custom_item",
    "name": "My Custom Item",
    "sku": "my-custom-item",
    "description": "My first custom item!",
    "quantity": 1,
    "price": {
      "amount": 10000
    }
  }
}'
var custom_item = {
  name: "My Custom Item",
  sku: "my-custom-item",
  description: "My first custom item!",
  quantity: 1,
  price: {
    amount: 10000
  }
};

Moltin.Cart("{CART_REFERENCE}").AddCustomItem(custom_item).then((cart) => {
  // Do something
});

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
name string The name of the custom item
sku string A SKU code to use for this custom item
description string A description of the custom item
quantity integer How many of this item to add to the cart
price object Contains pricing information
amount integer The price of the custom item

Retrieve a cart

curl -X GET https://api.moltin.com/v2/carts/{CART_REFERENCE} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Cart("{CART_REFERENCE}").Get().then((cart) => {
  // Do something
});

Returns an overview of the the cart corresponding to the passed cart reference.
A GET to /v2/carts/{CART_REFERENCE} which has not been previously created will return an empty cart.

HTTP Request

GET /v2/carts/{CART_REFERENCE}

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 as generated by you

Retrieve the cart items

curl -X GET https://api.moltin.com/v2/carts/{CART_REFERENCE}/items \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Cart("{CART_REFERENCE}").Items().then((cart) => {
  // Do something
});

Returns an array of cart items. A GET to /v2/carts/{CART_REFERENCE}/items which has not been previously been created will return an empty array.

HTTP Request

GET /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 as generated by you

Delete a cart

curl -X DELETE https://api.moltin.com/v2/carts/{CART_REFERENCE} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Cart("{CART_REFERENCE}").Delete().then((cart) => {
  // Do something
});

Removes all items from a cart, leaving you with an empty shopping basket.

HTTP Request

DELETE /v2/carts/{CART_REFERENCE}

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 as generated by you

Add a promotion to a cart

curl -X POST https://api.moltin.com/v2/carts/{CART_REFERENCE}/items \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "promotion_item",
    "code": "PROMO_CODE"
  }
}'
Moltin.Cart("{CART_REFERENCE}").AddPromotion("PROMO_CODE").then((cart) => {
  // Do something
});

Add a promotion_item to the cart.
promotion_items are a special case of cart_items which can be used to apply discounts or promotions to the cart.

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 as 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 promotion_item
code string The relevant promotion code

Update an item in a cart

curl -X "PUT" https://api.moltin.com/v2/carts/{CART_REFERENCE}/items/{ITEM_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "cart_item",
    "id": "76746981-f63a-45f4-ba9e-59773d89dc2e",
    "quantity": 2
  }
}'
Moltin.Cart("{CART_REFERENCE}").UpdateItemQuantity("76746981-f63a-45f4-ba9e-59773d89dc2e", 2).then((cart) => {
    // Do something
});

Update the properties of a cart_item already existing in the cart.
A successful cart_item update request will respond with the updated cart contents.

HTTP Request

PUT /v2/carts/{CART_REFERENCE}/items/{ITEM_ID}

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 as generated by you
item_id string The ID of the item you wish to remove from the cart (this is NOT the product_id)

Request Body

Attribute Type Description
data object Contains the request information
type string The type of item to be updated in the cart. In this case it must be cart_item
id string The ID of the item to be updated
quantity string The required quantity of the cart_item

Remove an item from a cart

curl -X DELETE https://api.moltin.com/v2/carts/{CART_REFERENCE}/items/{ITEM_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Cart("{CART_REFERENCE}").RemoveItem("76746981-f63a-45f4-ba9e-59773d89dc2e").then((cart) => {
  // Do something
});

Remove a specific cart_item that currently exists in the cart.
A successful cart_item delete request will respond with the updated cart contents.

HTTP Request

DELETE /v2/carts/{CART_REFERENCE}/items/{ITEM_ID}

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 as generated by you
item_id string The ID of the item you wish to remove from the cart (this is NOT the product_id)

Categories

Categories allow you to organize your products into hierarchical groups. That means these groups can also contain other categories, which can then be viewed in a tree structure.

The category object

{
  "data": {
    "id": "39a13b7e-f2d3-47a5-9bc5-1e98b198748c",
    "type": "category",
    "name": "Clothing",
    "slug": "clothing",
    "description": "Browse our clothing line",
    "status": "live"
  }
}
Attribute Type Description
id string The unique identifier for this category.
type string Represents the type of object being returned. required
name string The name of the category. required
slug string A unique slug identifier for the category. required
description string Any description for this category. required
status string live or draft depending on the category status. required

Category filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
name string eq, like eq(name,'Shoes')
slug string eq, like like(name,'Sh*')
status boolean eq eq(status,live)

Get a list of categories

Get a list of all categories.

curl https://api.moltin.com/v2/categories \
     -H "Authorization: Bearer XXXX"
Moltin.Categories.All().then((categories) => {
    // Do something
});

HTTP Request

GET /v2/categories

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Query String

Attribute Type Description
filter string Filter the results
include string categories, products

Get a category

Get a single category by id.

curl -X GET https://api.moltin.com/v2/categories/{CATEGORY_ID} \
     -H "Authorization: Bearer XXXX"
Moltin.Categories.Get("{CATEGORY_ID}").then((category) => {
    // Do something
});

HTTP Request

GET /v2/categories/{CATEGORY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
category_id string The id for the category requested.

Get the categories tree

Get a tree view of your categories.

curl -X GET https://api.moltin.com/v2/categories/tree \
     -H "Authorization: Bearer XXXX"
Moltin.Categories.Tree().then((categories) => {
    // Do something
});

HTTP Request

GET /v2/categories/tree

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Create a category

Create a new category.

curl -X POST https://api.moltin.com/v2/categories \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "category",
        "name": "Clothing",
        "slug": "clothing",
        "description": "Browse our clothing line",
        "status": "live"
     }
}'
var category = {
    name: "Clothing",
    slug: "clothing",
    description: "Browse our clothing line",
    status: "live"
}

Moltin.Categories.Create(category).then((response) => {
  // Do something
});

HTTP Request

POST /v2/categories

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the category. required
slug string A unique slug identifier for the category. required
description string Any description for this category. optional
status string live or draft depending on the category status (defaults to draft). optional

Update a category

Update an existing category.

curl -X PUT https://api.moltin.com/v2/categories/{CATEGORY_ID} \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "category",
        "id": "{CATEGORY_ID}",
        "name": "Clothes & Accessories",
        "slug": "clothes-and-accessories",
        "description": "Browse our clothing and accessories line",
        "status": "live"
     }
}'
var category = {
    name: "Clothes & Accessories",
    slug: "clothes-and-accessories",
    description: "Browse our clothing and accessories line",
    status: "live"
}

Moltin.Categories.Update("{CATEGORY_ID}", category).then((response) => {
  // Do something
});

HTTP Request

PUT /v2/categories/{CATEGORY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
category_id string The id for the category to update.

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the category. optional
slug string A unique slug identifier for the category. optional
description string Any description for this category. optional
status string live or draft depending on the category status. optional

Delete a category

Delete a category by id.

curl -X DELETE https://api.moltin.com/v2/categories/{CATEGORY_ID} \
    -H "Authorization: Bearer XXXX"
Moltin.Categories.Delete("{CATEGORY_ID}").then((response) => {
  // Do something
});

HTTP Request

DELETE /v2/categories/{CATEGORY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
category_id string The id for the category to delete.

Category Relationships

{
    "data": [{
        "type": "category",
        "id": "dfc28641-25f1-4895-9704-2f7d35303e65",
        "name": "Clothes",
        "status": "live",
        "slug": "clothes",
        "description": "Our clothing lines",
        "children": [
            {
                "type": "category",
                "id": "c0e6c74b-d03d-4d57-ad68-3cee82eed0cb",
                "name": "Mens",
                "status": "live",
                "slug": "mens",
                "description": "Mens Clothes"
            },
            {
                "type": "category",
                "id": "8a859a41-0781-48c7-a46c-ab3a32081f01",
                "name": "Womens",
                "status": "live",
                "slug": "womens",
                "description": "Womens Clothes"
            }
        ]
    }]
}

Relationships between categories allow you to establish a hierarchical tree structure between parents and children which can be useful for organising your catalogue into logical paths.

Consider the structure on the right (which you would use the category tree endpoint to retrieve).

The Clothes category has two children (Mens and Womens).

Clothes is therefore, by definition, the parent of Mens and Womens.

If you were to lay these out in a dynamic website, you would most likely have three pages:

Page Name URI Category ID
Clothes /clothes dfc28641-25f1-4895-9704-2f7d35303e65
Mens /clothes/mens c0e6c74b-d03d-4d57-ad68-3cee82eed0cb
Womens /clothes/womens 8a859a41-0781-48c7-a46c-ab3a32081f01

We use the parent /child(ren) analogy in the relationships between categories to other categories.

Create Category Relationships

Create a relationship to one or more other category. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/categories \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
      "parent": {
        "type": "category",
        "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
      },
      "children": [
        {
          "type": "category",
          "id": "1334e667-7b2b-4159-9e36-8a3b404901c8"
        }
      ]
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/categories/{CATEGORY_ID}/relationships/categories

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to make relationships to

Request Body

Attribute Type Description
parent object
parent.type string The type of related object (should be category)
parent.id string The id of the category
children array[object]
children[].type string The type of related object (should be category)
children[].id string The id of the category

Create Parent Category Relationship

Create a relationship to a parent category. If a relationships already exists, the one from the request will overwrite it.

curl -X "POST" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "category",
    "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
  }
}'
// Not supported

HTTP Request

POST /v2/categories/{CATEGORY_ID}/relationships/parent

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be category)
id string The id of the parent category

Update Parent Category Relationship

Change the parent of a category.

curl -X "PUT" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "category",
    "id": "c0e6c74b-d03d-4d57-ad68-3cee82eed0cb"
  }
}'
// Not supported

HTTP Request

PUT /v2/categories/{CATEGORY_ID}/relationships/parent

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to update relationships to

Request Body

Attribute Type Description
type string The type of related object (should be category)
id string The id of the new parent category

Delete Parent Category Relationship

Delete the parent of a category.

curl -X "DELETE" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX"
}'
// Not supported

HTTP Request

DELETE /v2/categories/{CATEGORY_ID}/relationships/parent

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to update relationships to

Create Child Category Relationships

Create a relationship to a parent category. If any relationship(s) already exists, new ones will be added to them.

curl -X "POST" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/categories/{CATEGORY_ID}/relationships/children

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be category)
id string The id of the parent category

Update Child Category Relationship

Update the children category. If any relationship(s) already exists, they will be removed.

curl -X "PUT" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "c0e6c74b-d03d-4d57-ad68-3cee82eed0cb"
    }
  ]
}'
// Not supported

HTTP Request

PUT /v2/categories/{CATEGORY_ID}/relationships/children

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be category)
id string The id of the parent category

Delete Child Category Relationship

Delete child categories of a category.

curl -X "DELETE" https://api.moltin.com/v2/categories/{CATEGORY_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "c0e6c74b-d03d-4d57-ad68-3cee82eed0cb"
    }
  ]
}'
// Not supported

HTTP Request

DELETE /v2/categories/{CATEGORY_ID}/relationships/parent

URL Parameters

URL Param Type Description
category_id string The id of the category you wish to update relationships to

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.

curl -X POST https://api.moltin.com/v2/carts/{CART_ID}/checkout \
     -H "Authorization: Bearer XXXX" \
     -d $'{
   "data": {
     "customer": {
       "id": "c8c1c511-beef-4812-9b7a-9f92c587217c"
     },
     "billing_address": {
       "first_name": "John",
       "last_name": "Doe",
       "company_name": "Moltin",
       "line_1": "2nd Floor British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne & Wear",
       "country": "UK"
     },
     "shipping_address": {
       "first_name": "John",
       "last_name": "Doe",
       "company_name": "Moltin",
       "line_1": "2nd Floor British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne & Wear",
       "country": "UK"
       "instructions": "Leave in porch"
     }
   }
}'
var address = {
  first_name: "John",
  last_name: "Doe",
  line_1: "2nd Floor British India House",
  line_2: "15 Carliol Square",
  city: "Newcastle Upon Tyne",
  postcode: "NE1 6UF",
  county: "Tyne & Wear",
  country: "United Kingdom"
};

Moltin.Cart("{CART_REFERENCE}").Checkout("{CUSTOMER_ID}", address);

HTTP Request

POST /v2/carts/{CART_REFERENCE}/checkout

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
customer.id string The unique identifier for this customer. required
billing_address.first_name string The first name of the billing customer. required
billing_address.last_name string The last name of the billing customer. required
billing_address.company_name string The billing company name.
billing_address.line_1 string The first line of the billing address. required
billing_address.line_2 string The second line of the billing address.
billing_address.city string The city of the billing address.
billing_address.postcode string The postcode of the billing address. required
billing_address.county string The county of the billing address. required
billing_address.country string The country of the billing address. required
shipping_address.first_name string The first name of the shipping customer. required
shipping_address.last_name string The last name of the shipping customer. required
shipping_address.company_name string The shipping company name.
shipping_address.line_1 string The first line of the shipping address. required
shipping_address.line_2 string The second line of the shipping address.
shipping_address.city string The city of the shipping address.
shipping_address.postcode string The postcode of the shipping address. required
shipping_address.county string The county of the shipping address. required
shipping_address.country string The country of the shipping address. required
shipping_address.instructions string Optional shipping instructions.

Using a customer object

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

curl -X POST https://api.moltin.com/v2/carts/{CART_ID}/checkout \
     -H "Authorization: Bearer XXXX" \
     -d $'{
   "data": {
     "customer": {
       "email": "john@moltin.com",
       "name": "John Doe"
     },
     "billing_address": {
       "first_name": "John",
       "last_name": "Doe",
       "company_name": "Moltin",
       "line_1": "2nd Floor British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne & Wear",
       "country": "UK"
     },
     "shipping_address": {
       "first_name": "John",
       "last_name": "Doe",
       "company_name": "Moltin",
       "line_1": "2nd Floor British India House",
       "line_2": "15 Carliol Square",
       "city": "Newcastle upon Tyne",
       "postcode": "NE1 6UF",
       "county": "Tyne & Wear",
       "country": "UK"
       "instructions": "Leave in porch"
     }
   }
}'
var customer = {
  email: "john@moltin.com",
  name: "John Doe"
};
var address = {
  first_name: "John",
  last_name: "Doe",
  line_1: "2nd Floor British India House",
  line_2: "15 Carliol Square",
  city: "Newcastle Upon Tyne",
  postcode: "NE1 6UF",
  county: "Tyne & Wear",
  country: "United Kingdom"
};

Moltin.Cart("{CART_REFERENCE}").Checkout(customer, address);

HTTP Request

POST /v2/carts/{CART_REFERENCE}/checkout

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
customer.id string The unique identifier for this customer. required
billing_address.first_name string The first name of the billing customer. required
billing_address.last_name string The last name of the billing customer. required
billing_address.company_name string The billing company name.
billing_address.line_1 string The first line of the billing address. required
billing_address.line_2 string The second line of the billing address.
billing_address.city string The city of the billing address.
billing_address.postcode string The postcode of the billing address. required
billing_address.county string The county of the billing address. required
billing_address.country string The country of the billing address. required
shipping_address.first_name string The first name of the shipping customer. required
shipping_address.last_name string The last name of the shipping customer. required
shipping_address.company_name string The shipping company name.
shipping_address.line_1 string The first line of the shipping address. required
shipping_address.line_2 string The second line of the shipping address.
shipping_address.city string The city of the shipping address.
shipping_address.postcode string The postcode of the shipping address. required
shipping_address.county string The county of the shipping address. required
shipping_address.country string The country of the shipping address. required
shipping_address.instructions string Optional shipping instructions.

Collections

Collections allow you to organize your products into hierarchical groups. Where a dress product might be in the category Clothing, the individual product might also be in the collection Summer.

The collection object

{
  "data": {
    "id": "5ab3deca-1f11-47b7-a409-24ea3234d72c",
    "type": "collection",
    "name": "Winter Season",
    "slug": "winter-season",
    "description": "Our Winter Season is now live!",
    "status": "live"
  }
}
Attribute Type Description
id string The unique identifier for this collection.
type string Represents the type of object being returned. required
name string The name of the collection. required
slug string A unique slug identifier for the collection. required
description string Any description for this collection. required
status string live or draft depending on the collection status. required

Collection filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
name string eq, like eq(name,'Summer')
slug string eq, like like(name,'Summer*')
status boolean eq eq(status,live)

Get a list of collections

Get a list of all collections.

curl -X GET https://api.moltin.com/v2/collections \
     -H "Authorization: Bearer XXXX"
Moltin.Collections.All().then((collections) => {
    // Do something
});

HTTP Request

GET /v2/collections

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Query String

Attribute Type Description
filter string Filter the results
include string collections, products

Get a collection

Get a single collection by id.

curl -X GET https://api.moltin.com/v2/collections/{COLLECTION_ID} \
     -H "Authorization: Bearer XXXX"
Moltin.Collections.Get('{COLLECTION_ID}').then((collection) => {
    // Do something
});

HTTP Request

GET /v2/collections/{COLLECTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
collection_id string The id for the collection requested.

Get the collections tree

Get a tree view of your collections.

curl -X GET https://api.moltin.com/v2/collections/tree \
     -H "Authorization: Bearer XXXX"
Moltin.Collections.Tree().then((collections) => {
    // Do something
});

HTTP Request

GET /v2/collections/tree

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Create a collection

Create a new collection.

curl -X POST https://api.moltin.com/v2/collections \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "collection",
        "name": "Winter Season",
        "slug": "winter-season",
        "description": "Our Winter Season is now live!",
        "status": "live"
     }
}'
var collection = {
    name: "Winter Season",
    slug: "winter-season",
    description: "Our Winter Season is now live!",
    status: "live"
}

Moltin.Collections.Create(collection).then((response) => {
  // Do something
});

HTTP Request

POST /v2/collections

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the collection. required
slug string A unique slug identifier for the collection. required
description string Any description for this collection. optional
status string live or draft depending on the collection status (defaults to draft). optional

Update a collection

Update an existing collection.

curl -X PUT https://api.moltin.com/v2/collections/{COLLECTION_ID} \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "collection",
        "id": "{COLLECTION_ID}",
        "name": "Summer Season",
        "slug": "summer-season",
        "description": "Our Summer Season is now live!",
        "status": "live"
     }
}'
var collection = {
    name: "Summer Season",
    slug: "summer-season",
    description: "Our Summer Season is now live!",
    status: "live"
}

Moltin.Collections.Update("{COLLECTION_ID}", collection).then((response) => {
  // Do something
});

HTTP Request

PUT /v2/collections/{COLLECTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
collection_id string The id for the collection to update.

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the collection. optional
slug string A unique slug identifier for the collection. optional
description string Any description for this collection. optional
status string live or draft depending on the collection status. optional

Delete a collection

Delete a collection by id.

curl -X DELETE https://api.moltin.com/v2/collections/{COLLECTION_ID} \
    -H "Authorization: Bearer XXXX"
Moltin.Collections.Delete("{COLLECTION_ID}").then((response) => {
  // Do something
});

HTTP Request

DELETE /v2/collections/{COLLECTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
collection_id string The id for the collection to delete.

Collection Relationships

{
    "data": [{
        "type": "collection",
        "id": "5ab3deca-1f11-47b7-a409-24ea3234d72c",
        "name": "Summer",
        "status": "live",
        "slug": "summer",
        "description": "Our summer colelction",
        "children": [
            {
                "type": "collection",
                "id": "85f4f643-e66b-4deb-b9da-dd14c5cbc013",
                "name": "Shorts",
                "status": "live",
                "slug": "shorts",
                "description": "Summer Shorts"
            },
            {
                "type": "collection",
                "id": "1e129fcc-146d-47ab-a786-22b94dd7e4fc",
                "name": "Shirts",
                "status": "live",
                "slug": "shirts",
                "description": "Summer Shirts"
            }
        ]
    }]
}

Relationships between collections allow you to establish a hierarchical tree structure between parents and children which can be useful for organising your catalogue into logical paths.

Consider the structure on the right (which you would use the collection tree endpoint to retrieve).

The Summer collection has two children (Shorts and Shirts).

Summer is therefore, by definition, the parent of Shorts and Shirts.

If you were to lay these out in a dynamic website, you would most likely have three pages:

Page Name URI Collection ID
Summer /summer 5ab3deca-1f11-47b7-a409-24ea3234d72c
Shorts /summer/shorts 85f4f643-e66b-4deb-b9da-dd14c5cbc013
Shirts /summer/shirts 1e129fcc-146d-47ab-a786-22b94dd7e4fc

We use the parent /child(ren) analogy in the relationships between collections to other collections.

Create Collection Relationships

Create a relationship to one or more other collection. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/collections \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
      "parent": {
        "type": "collection",
        "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
      },
      "children": [
        {
          "type": "collection",
          "id": "1334e667-7b2b-4159-9e36-8a3b404901c8"
        }
      ]
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/collections/{COLLECTION_ID}/relationships/collections

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to make relationships to

Request Body

Attribute Type Description
parent object
parent.type string The type of related object (should be collection)
parent.id string The id of the collection
children array[object]
children[].type string The type of related object (should be collection)
children[].id string The id of the collection

Create Parent Collection Relationship

Create a relationship to a parent collection. If a relationships already exists, the one from the request will overwrite it.

curl -X "POST" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "collection",
    "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
  }
}'
// Not supported

HTTP Request

POST /v2/collections/{COLLECTION_ID}/relationships/parent

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be collection)
id string The id of the parent collection

Update Parent Collection Relationship

Change the parent of a collection.

curl -X "PUT" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type": "collection",
    "id": "85f4f643-e66b-4deb-b9da-dd14c5cbc013"
  }
}'
// Not supported

HTTP Request

PUT /v2/collections/{COLLECTION_ID}/relationships/parent

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to update relationships to

Request Body

Attribute Type Description
type string The type of related object (should be collection)
id string The id of the new parent collection

Delete Parent Collection Relationship

Delete the parent of a collection.

curl -X "DELETE" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX"
}'
// Not supported

HTTP Request

DELETE /v2/collections/{COLLECTION_ID}/relationships/parent

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to update relationships to

Create Child Collection Relationships

Create a relationship to a parent collection. If any relationship(s) already exists, new ones will be added to them.

curl -X "POST" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    }
  ]
}'
// Not supported

HTTP Request

POST /v2/collections/{COLLECTION_ID}/relationships/children

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be collection)
id string The id of the parent collection

Update Child Collection Relationship

Update the children collection. If any relationship(s) already exists, they will be removed.

curl -X "PUT" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/children \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "85f4f643-e66b-4deb-b9da-dd14c5cbc013"
    }
  ]
}'
// Not supported

HTTP Request

PUT /v2/collections/{COLLECTION_ID}/relationships/children

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to make relationships to

Request Body

Attribute Type Description
type string The type of related object (should be collection)
id string The id of the parent collection

Delete Child Collection Relationship

Delete child collections of a collection.

curl -X "DELETE" https://api.moltin.com/v2/collections/{COLLECTION_ID}/relationships/parent \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "85f4f643-e66b-4deb-b9da-dd14c5cbc013"
    }
  ]
}'
// Not supported

HTTP Request

DELETE /v2/collections/{COLLECTION_ID}/relationships/parent

URL Parameters

URL Param Type Description
collection_id string The id of the collection you wish to update relationships to

Request Body

Attribute Type Description
data array[object]
data[].type string The type of related object (should be collection)
data[].id string The id of the child collection

Currencies

The currency object

The currency object is a representation of a currency in moltin.

{
  "data": {
    "id": "7e5dd85a-f1eb-4025-8d2a-42ff3a37828f",
    "type": "currency",
    "code": "USD",
    "exchange_rate": 1,
    "format": "${price}",
    "decimal_point": ".",
    "thousand_separator": ",",
    "decimal_places": 2,
    "default": true,
    "enabled": true,
    "links": {
      "self": "https://api.moltin.com/currencies/7e5dd85a-f1eb-4025-8d2a-42ff3a37828f"
    },
    "meta": {
      "timestamps": {
        "created_at": "2017-02-17T19:57:39.882Z",
        "updated_at": "2017-09-12T10:50:09.582Z"
      }
    }
  }
}
Attribute Type Description
id string The unique identifier for this currency
type string Represents the type of object being returned
code string The currency code
exchange_rate float The exchange rate
format string How a formatted currency is returned
decimal_point string The decimal point character
thousand_separator string The thousand seperator character
decimal_places string How many decimal places the currency is formatted to
default boolean true if default currency, false if not
enabled boolean true if currency enabled, false if not
links object A collection of URLs related to this resource
links.self string The URL of this currency
meta object Additional information for this currency
meta.timestamps object Timestamps for this currency
meta.timestamps.created_at string The creation date of this currency
meta.timestamps.updated_at string The updated date of this currency

Get a list of currencies

Get a list of all currencies.

curl -X GET https://api.moltin.com/v2/currencies \
     -H "Authorization: Bearer XXXX"
Moltin.Currencies.All().then((currency) => {
  // Do something
});

HTTP Request

GET /v2/currencies

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get a currency

Get a single currency by id.

curl -X GET https://api.moltin.com/v2/currencies/{CURRENCY_ID} \
     -H "Authorization: Bearer XXXX"
Moltin.Currencies.Get("{CURRENCY_ID}").then((currency) => {
  // Do something
});

HTTP Request

GET /v2/currencies/{CURRENCY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
currency_id string The id for the currency requested.

Create a currency

Create a new currency.

curl -X POST https://api.moltin.com/v2/currencies \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
           "code": "GBP",
           "exchange_rate": 1,
           "format": "£{price}",
           "decimal_point": ".",
           "thousand_separator": ",",
           "decimal_places": 2,
           "default": false,
           "enabled": true
     }
}'
var currency = {
    code: "GBP",
    exchange_rate: 1,
    format: "£{price}",
    decimal_point: ".",
    thousand_separator: ",",
    decimal_places: 2,
    default: false,
    enabled: true
}

Moltin.Currencies.Create(currency).then((response) => {
  // Do something
});

HTTP Request

POST /v2/currencies

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
code String The currency code. required
exchange_rate float The exchange rate from the default. required
format string How a formatted currency is returned. required
decimal_point string The decimal point character. required
thousand_separator string The thousand seperator character. required
decimal_places string How many decimal places the currency is formatted to. required
default boolean true if default currency, false if not. required
enabled boolean true if currency enabled, false if not. required

Update a currency

Update an existing currency.

curl -X POST https://api.moltin.com/v2/currencies/{CURRENCY_ID} \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
           "enabled": false
     }
}'
var currency = {
    enabled: false
}

Moltin.Currencies.Update("{CURRENCY_ID}", currency).then((response) => {
  // Do something
});

HTTP Request

PUT /v2/currencies/{CURRENCY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
code string The currency code. not required
exchange_rate float The exchange rate from the default. not required
format string How a formatted currency is returned. not required
decimal_point string The decimal point character. not required
thousand_separator string The thousand separator character. not required
decimal_places string How many decimal places the currency is formatted to. not required
default boolean true if default currency, false if not. not required
enabled boolean true if currency enabled, false if not. not required

Delete a currency

Delete a currency by id.

curl -X DELETE https://api.moltin.com/v2/currencies/{CURRENCIES_ID} \
    -H "Authorization: Bearer XXXX"
Moltin.Currencies.Delete("{CURRENCY_ID}").then((response) => {
  // Do something
});

HTTP Request

DELETE /v2/currencies/{CURRENCY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
currency_id string The id for the currency requested.

Customers

The customer object

The customers object is a representation of a customer in moltin.

{
  "data": {
    "id": "c8c1c511-beef-4812-9b7a-9f92c587217c",
    "type": "customer",
    "name": "Ron Swanson",
    "email": "ron@swanson.com",
    "password": true
  }
}
Attribute Type Description
id string The unique identifier for this customer
type string Represents the type of object being returned. required
name string The full name of the customer. required
email string The customer email. required
password boolean The customers password. required

The customer token object

The customers object is a representation of a customer in moltin.

{
  "data": {
    "type": "token",
    "id": "36f05940-0d38-411a-8909-3aea58bc1f09",
    "customer_id": "79cc0486-bbdf-491b-a0a2-722383b6288b",
    "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiI3OWNjMDQ4Ni1iYmRmLTQ5MWItYTBhMi03MjIzODNiNjI4OGIiLCJuYW1lIjoiUm9uIFN3YW5zb24iLCJleHAiOjE1MTA2ODQyMDAsImlhdCI6MTUxMDU5NzgwMCwianRpIjoiMzZmMDU5NDAtMGQzOC00MTFhLTg5MDktM2FlYTU4YmMxZjA5In0=.ea948e346d0683803aa4a2c09441bcbf7c79bd9234bed2ce8456ab3af257ea9f",
    "expires": 1510684200
  }
}
Attribute Type Description
id string The unique identifier for this customer
type string Represents the type of object being returned
customer_id string The id of the customer from which the token is generated
token string The JSON Web Token to be used for other endpoints
expires timestamp The epoch time that this token expires at

Customer filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
email string eq eq(mail,jim@bob.com)

Get a list of customers

Get a list of all customers.

curl -X GET https://api.moltin.com/v2/customers \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Customers.All().then((customer) => {
  // Do something
});

HTTP Request

GET /v2/customers

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer orders. optional

Query String

Attribute Type Description
filter string Filter the results

Get a customer

Get a single customer by id.

curl -X GET https://api.moltin.com/v2/customers/{CUSTOMER_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Customers.Get("{CUSTOMER_ID}").then((customer) => {
  // Do something
});

HTTP Request

GET /v2/customers/{CUSTOMER_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer orders. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer requested.

Create a customer

Create a new customer.

curl -X POST https://api.moltin.com/v2/customers \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
     "type": "customer",
     "name": "Ron Swanson",
     "email": "ron@swanson.com",
     "password": "mysecretpassword",
     }
}'
var customer = {
    name: "Ron Swanson",
    email: "ron@swanson.com",
    password: "mysecretpassword",
}

Moltin.Customers.Create(customer).then((response) => {
  // Do something
});

HTTP Request

POST /v2/customers

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The full name of the customer. required
email string The customer email. required
password string The customers password. not required

Update a customer

Update an existing customer.

curl -X PUT https://api.moltin.com/v2/customers/{CUSTOMER_ID} \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
           "email": "ron@swanson.com"
     }
}'
var customer = {
    email: "ron@swanson.com"
}

Moltin.Customers.Update("{CUSTOMER_ID}", customer).then((response) => {
  // Do something
});

HTTP Request

PUT /v2/customers/{CUSTOMER_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer orders. optional

URL Parameters

URL Param Type Description
customer_id string The id for the customer requested.

Request Body

Attribute Type Description
type string Represents the type of object being returned. not required
name string The full name of the customer. not required
email string The customer email. not required
password string The customers password. not required

Delete a customer

Delete a customer by id.

curl -X DELETE https://api.moltin.com/v2/customers/{CUSTOMER_ID} \
    -H "Authorization: Bearer XXXX"
Moltin.Customers.Delete("{CUSTOMER_ID}").then((response) => {
  // Do something
});

HTTP Request

DELETE /v2/customers/{CUSTOMER_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
customer_id string The id for the customer requested.

Generate a customer token

Generate a new customer token for a given customer. Customer tokens can be used for other endpoints to make implicit requests to what would normally be data scoped to client_credentials.

curl -X POST https://api.moltin.com/v2/customers/tokens \
    -H "Authorization: Bearer XXXX" \
    -d $'{
    "data":{
        "type": "token",
        "email": "ron@swanson.com",
        "password": "mysecretpassword"
    }
}'
async getCustomerOrders() {
  // Get a customer token
  var customer = await Moltin.Customers.Token("ron@swanson.com", "mysecretpassword");

  // Use token in request header to get orders tied to customer
  await Moltin.Orders.All(customer.token);
}

HTTP Request

POST /v2/customers/tokens

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Must be token. required
email string The customer email. required
password string The customers password. required

Files

Files are immutable. Once they have been added, they cannot be updated with a PUT request but they can be removed via a DELETE and another file can be added in its place via a POST.

When you create a new file, you must set your request to use Content-Type: multipart/form-data.

The file object

A cart object is a representation of the current state of your shopping basket.

{
  "data": {
    "id": "272d3ff0-5034-4986-8786-0ff97450745d",
    "type": "file",
    "link": {
      "href": "https://s3-eu-west-1.amazonaws.com/bkt-api-moltin-com/2a85964e-cb3d-482a-ab02-0f0e47ab5662/273d3ff0-5034-4986-8786-0ff97450745.jpg"
    },
    "file_name": "image.jpg",
    "mime_type": "image/jpeg",
    "file_size": 20953,
    "public": true,
    "meta": {
      "dimensions": {
        "width": 1600,
        "height": 800
      },
      "timestamps": {
        "created_at": "2017-08-14T10:47:45.191Z"
      }
    },
    "links": {
      "current": "https://api.moltin.com/v2/files/272d3ff0-5034-4986-8786-0ff97450745d"
    }
  }
}
Attribute Type Description
id string The unique identifier for this file.
type string Represents the type of object being returned
link object The file link object.
link.href string The publicly available URL for this file.
file_name string The name of the file.
mime_type string The mime type of the file.
file_size integer The size of the file.
public boolean Whether the file is public or not.
meta object Additional meta information.
meta.dimensions object The dimensions object.
meta.dimensions.width integer The width of the file.
meta.dimensions.height integer The height of the file.
meta.dimensions.timestamps object Timestamps for this file.
meta.timestamps.created_at string The creation date of this file.
links object A collection of URLs related to this resource.
links.current object The URL of this file object.

File filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
file_name string eq, like eq(file_name,'MyImage.jpg')
width integer gt, ge, lt, le gt(width,200)
height integer gt, ge, lt, le lt(height,500)
public bolean eq eq(public,true)
file_size integer gt, ge, lt, le le(file_size,20953)

Get a list of files

Get a list of all files.

curl -X GET https://api.moltin.com/v2/files \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/files

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Query String

Attribute Type Description
filter string Filter the results

Get a file

Get a single file by id.

curl -X GET https://api.moltin.com/v2/files/{FILE_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/files/{FILE_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
file_id string The id for the file requested.

Create a file

Upload a new file.

curl -X POST https://api.moltin.com/v2/files \
    -H "Authorization: Bearer XXXX" \
    -H "Content-Type: multipart/form-data" \
    -F file=@/path/to/file \
    -d public=1
Not supported yet

HTTP Request

POST /v2/files

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
file string The file you want to upload.
public boolean Is this file public, we only support true on this endpoint right now.

Delete a file

Delete a file by id.

curl -X DELETE https://api.moltin.com/v2/files/{FILE_ID} \
    -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/files/{FILE_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
file_id string The id for the file requested.

Flows

Flows is a data overlay system which allows you to attach additional data to the core entities in your ecommerce store or to create new entities that you can access.

The flows system is comprised of three main concepts; flows, fields and entries.

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).

The flow object

{
  "data": {
    "id": "b2895a6c-8c12-4515-9e4b-a305769e7b25",
    "type": "flow",
    "name": "Products",
    "slug": "products",
    "description": "Extends the default product object",
    "enabled": true
  }
}
Attribute Type Description
id string The unique identifier for this flow.
type string Represents the type of object being returned.
name string The name of the flow.
slug string A unique slug identifier for the flow.
description string Any description for this flow.
enabled bool true if enabled, false if not.

Get a list of flows

Get a list of all flows

curl https://api.moltin.com/v2/flows \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/flows

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get a flow

Get a single flow

curl https://api.moltin.com/v2/flows/{FLOW_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/flows/{FLOW_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
flow_id string The id for the flow you are requesting.

Create a flow

Create a new flow.

curl -X "POST" "https://api.moltin.com/v2/flows" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "flow",
    "name": "Products",
    "slug": "products",
    "description": "Extends the default product object",
    "enabled": true
  }
}'
Not supported yet

HTTP Request

POST /v2/flows

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned.
name string The name of the flow. required
slug string A unique slug identifier for the flow. required
description string Any description for this flow. required
enabled bool true if enabled, false if not. required

Update a flow

Update an existing flow.

curl -X "POST" "https://api.moltin.com/v2/flows/{FLOW_ID}" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "id": "{FLOW_ID}",
    "type": "flow",
    "name": "Categories",
    "slug": "categories",
    "description": "Extends the default category object",
    "enabled": true
  }
}'
Not supported yet

HTTP Request

PUT /v2/flows/{FLOW_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
id string The unique identifier for this flow. required
type string Represents the type of object being returned. required
name string The name of the flow. optional
slug string A unique slug identifier for the flow. optional
description string Any description for this flow. optional
enabled bool true if enabled, false if not. optional

Delete a flow

Delete a flow by id.

curl -X DELETE https://api.moltin.com/v2/flows/{FLOW_ID} \
    -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/flows/{FLOW_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
flow_id string The id for the field you are requesting to be deleted.

The field object

{
  "data": {
    "id": "3eab0b88-4fb5-4504-8bd0-d1118819643d",
    "type": "field",
    "name": "Product Rating",
    "slug": "product-rating",
    "field_type": "integer",
    "validation_rules": [
        {
            "type": "between",
            "options": {
                "from": 1,
                "to": 5
            }
        }
    ],
    "description": "Average rating as given by our users",
    "required": false,
    "unique": false,
    "default": 0,
    "enabled": true,
    "relationships": {
        "flow": {
            "data": {
                "type": "flow",
                "id": "b2895a6c-8c12-4515-9e4b-a305769e7b25"
            }
        }
    }
  }
}
Attribute Type Description
id string The unique identifier for this field.
type string Represents the type of object being returned.
name string The name of the field.
slug string A unique slug identifier for the field.
field_type string The type of field - string, integer, boolean, float, date
validation_rules array[object] See Flow Field Validation Rules
description string Any description for this field.
required bool true if required on input, false if not.
unique bool true if each entry should be unique, false if not.`
default mixed A default value if none is supplied and field is not required.
enabled bool If this field is enabled on the flow this should be true, otherwise false.
relationships object A relationship object to link this field to a flow.

Get a list of fields

Get a list of all fields

curl https://api.moltin.com/v2/fields \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/fields

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get a field

Get a single field

curl https://api.moltin.com/v2/fields/{FIELD_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/field/{FIELD_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
field_id string The id for the field you are requesting.

Create a field

Create a new field.

curl -X "POST" "https://api.moltin.com/v2/fields" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "field",
    "name": "Product Rating",
    "slug": "product-rating",
    "field_type": "integer",
    "validation_rules": [
        {
            "type": "between",
            "options": {
                "from": 1,
                "to": 5
            }
        }
    ],
    "description": "Average rating as given by our users",
    "required": false,
    "unique": false,
    "default": 0,
    "enabled": true,
    "relationships": {
        "flow": {
            "data": {
                "type": "flow",
                "id": "b2895a6c-8c12-4515-9e4b-a305769e7b25"
            }
        }
    }
  }
}'
Not supported yet

HTTP Request

POST /v2/fields

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
name string The name of the field. required
slug string A unique slug identifier for the field. required
field_type string The type of field - string, integer, boolean, float, date. required
validation_rules array[object] See Flow Field Validation Rules optional
description string Any description for this field. required
required bool true if required on input, false if not. required
unique bool true if each entry should be unique, false if not. required
default mixed A default value if none is supplied and field is not required. optional
enabled bool If this field is enabled on the flow this should be true, otherwise false. required
relationships object A relationship object to link this field to a flow. optional

Update a field

Update an existing field.

curl -X "POST" "https://api.moltin.com/v2/fields/{FIELD_ID}" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "id": "{FIELD_ID}",
    "type": "field",
    "name": "Average Product Rating",
  }
}'
Not supported yet

HTTP Request

PUT /v2/fields/{FIELD_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
field_id string The id for the field you are requesting to be updated.

Request Body

Attribute Type Description
id string The unique identifier for this field. required
type string Represents the type of object being returned. required
name string The name of the field. optional
slug string A unique slug identifier for the field.
field_type string The type of field - string, integer, boolean, float, date. optional
validation_rules array[object] See Flow Field Validation Rules optional
description string Any description for this field. optional
required bool true if required on input, false if not. optional
unique bool true if each entry should be unique, false if not. optional
default mixed A default value if none is supplied and field is not required. optional
enabled bool If this field is enabled on the flow this should be true, otherwise false. optional
relationships object A relationship object to link this field to a flow. optional

Delete a field

Delete a field by id.

curl -X DELETE https://api.moltin.com/v2/fields/{FIELD_ID} \
    -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/fields/{FIELD_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
field_id string The id for the field you are requesting to be deleted.

The entry object

{
  "data": {
    "id": "235a7f6b-dc70-4f06-85bc-b8b916cc2c24",
    "type": "entry",
    "product-rating": 3,
    "product-code": "ABC"
  }
}
Attribute Type Description
id string The unique identifier for this entry.
type string Represents the type of object being returned.
{FIELD_SLUG} mixed The {FIELD_SLUG} key depends on the field's slug value. The value is of fields field_type.

Get a list of entries

Get a list of all entries for a flow.

curl https://api.moltin.com/v2/flows/{FLOW_SLUG}/entries \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/flows/{FLOW_SLUG}/entries

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
flow_slug string The slug for the flow you are requesting entries for.

Get an entry

Get a single entry

curl https://api.moltin.com/v2/flows/{FLOW_SLUG}/entries/{ENTRY_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/flows/{FLOW_SLUG}/entries/{ENTRY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
flow_slug string The slug for the flow you are requesting an entry for.
entry_id string The id of the entry you are requesting.

Create an entry

Create a new entry for a flow.

curl -X "POST" "https://api.moltin.com/v2/flows/{FLOW_SLUG}/entries" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "entry",
    "{FIELD_SLUG}": "a value",
  }
}'
Not supported yet

HTTP Request

POST /v2/flows/{FLOW_SLUG}/entries

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being returned.
{FIELD_SLUG} string The name of the flow. required

URL Parameters

URL Param Type Description
flow_slug string The slug for the flow you are requesting an entry for.

Update an entry

Update an existing entry for a flow.

curl -X "POST" "https://api.moltin.com/v2/flows/{FLOW_SLUG}/entries/{ENTRY_ID}" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "id": "{ENTRY_ID}",
    "type": "entry",
    "{FIELD_SLUG}": "a new value",
  }
}'
Not supported yet

HTTP Request

POST /v2/flows/{FLOW_SLUG}/entries/{ENTRY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
{ENTRY_ID} string
type string Represents the type of object being returned.
{FIELD_SLUG} string The name of the flow. required

Note: you can have multiple {FIELD_SLUG}'s in the request body if they are related to the flow.

URL Parameters

URL Param Type Description
flow_slug string The slug for the flow you are requesting an entry for.
entry_id string The id of the entry you are updating.

Delete an entry

Delete an entry by id.

curl -X DELETE https://api.moltin.com/v2/flows/{FLOW_SLUG}/entries/{ENTRY_ID} \
    -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/flows/{FLOW_ID}/entries/{ENTRY_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
flow_slug string The slug for the flows you are requesting entries for.
entry_id string The id of the entry you are requesting to delete.

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).

The integration object

{
  "data": {
    "id": "328b4e0b-4032-48d0-8c85-04cc4c0a331d",
    "type": "integration",
    "name": "Warehouse Notification",
    "description": "Alert the warehouse when a new order is created to prepare the order for shipping",
    "integration_type": "webhook",
    "enabled": true,
    "observes": [
      "order.created"
    ],
    "configuration": {
      "url": "https://yourwebsite.com/order-created-notification",
      "secret_key": "secret_key_to_validate_on_your_endpoint"
    }
  }
}

The integration object is the represetation of an intergration in moltin.

Attribute Type Description
id string The unique identifier for this integration.
type string Represents the type of object being returned.
name string The name of the integration.
description string Any description for this integration.
integration_type string webhook or email depending on the desirable action of this integration.
enabled bool true if it should be triggered when observable events occur, false if not.
observes array[string] an array of events to observe.
configuration object a webhook or email configuration object.

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

{
  "url": "https://yourwebsite.com/order-created-notification",
  "secret_key": "secret_key_to_validate_on_your_endpoint"
}

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

Email Configuration

{
  "smtp_host": "",
  "smtp_port": "",
  "smtp_username": "",
  "smtp_password": "",
  "email_from_address": "",
  "email_from_name": "",
  "email_body_html": "",
  "email_body_plain": "",
  "email_body_url": "",
  "email_body_url_secret_key": "",
  "email_subject": "",
  "email_to_address": "",
  "email_to_name": ""
}

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:

Entity Action Observable Key
File Created file.created
Deleted file.deleted
Integration Created integration.created
Updated integration.updated
Deleted integration.deleted
Order Created order.created
Updated order.updated
Payment Gateway Updated payment-gateway.updated
Product Created product.created
Updated product.updated
Deleted product.deleted
Settings Created settings.created
Updated settings.updated
Stock Transaction Created stock-transaction.created
Transaction Created transaction.created
Updated transaction.updated

Payload

{
  "id": "8be8428e-4408-4172-a4cd-f42180330fe6",
  "integration": {
    "id": "71679ff8-36c1-4f8f-8ed2-cea50550d78c",
    "integration_type": "webhook",
    "name": "Order Created",
    "description": "An example order created integration"
  },
  "trigger": "order.created",
  "attempt": 1,
  "resources": [{
    "type": "order",
    "id": "32f8df65-8a31-4c43-9ed8-5d87127d9fdd",
    // ... other order attributes
  }]
}

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.

Attribute Type Description
id string a unique ID for this particular job.
integration object the integration being fired.
trigger string the observable event that caused this to be triggered.
attempt integer the number of attempts to deliver this notification.
resources array[object] any resources that have been affected by this event.

Responding to Integrations

{
  "proceed": true,
  "email": {
    "subject": "A new subject",
    "html": "<html><body><h1>Custom Content</h1></body></html>",
    "plain": "Custom Content\n"
  }
}

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.

Get a list of integrations

Get a list of all integrations.

curl https://api.moltin.com/v2/integrations \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get an integration

Get a single integration by id.

curl https://api.moltin.com/v2/integrations/{INTEGRATION_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations/{INTEGRATION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
integration_id string The id for the integration requested.

Create an integration

Create a new integration.

curl -X POST https://api.moltin.com/v2/integrations \
     -H "Authorization: Bearer: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "integration",
    "name": "Webhook Test"
    "description": "A test webhook",
    "enabled": false,
    "observes": [
      "product.created",
      "product.updated"
    ],
    "integration_type": "webhook",
    "configuration": {
      "url": "https://yourdomain.com/moltin-notifications"
    }
  }
}'

HTTP Request

POST /v2/integrations

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object. required
name string The name of the integration. required
description string Any description for this integration. optional
integration_type string webhook or email depending on the desirable action of this integration. required
enabled bool true if it should be triggered when observable events occur, false if not. optional
observes array[string] an array of events to observe. required
configuration object a webhook or email configuration object. required

Update an integration

Update an existing integration

curl -X PUT https://api.moltin.com/v2/integrations/{INTEGRATION_ID} \
     -H "Authorization: Bearer: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "integration",
    "name": "ProductWebhook"
    "description": "Our product webhook",
    "enabled": true,
    "observes": [
      "product.created",
      "product.updated",
      "product.deleted"
    ],
    "integration_type": "webhook",
    "configuration": {
      "url": "https://yourdomain.com/product-notifications"
    }
  }
}'

HTTP Request

PUT /v2/integrations/{INTEGRATION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
id string The id for the integration to update. required
type string Represents the type of object. required
name string The name of the integration. optional
description string Any description for this integration. optional
integration_type string webhook or email depending on the desirable action of this integration. optional
enabled bool true if it should be triggered when observable events occur, false if not. optional
observes array[string] an array of events to observe. optional
configuration object a webhook or email configuration object. optional

URL Parameters

URL Param Type Description
integration_id string The id for the integration to update.

Delete an integration

Delete an integration by id.

curl -X DELETE https://api.moltin.com/v2/integrations/{INTEGRATION_ID} \
    -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/integrations/{INTEGRATION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
integration_id string The id for the integration to be deleted.

Logs & Debugging

We make logs available so that you can debug your own application.

GET https://api.moltin.com/v2/integrations/logs : a response with all logs for your store. GET https://api.moltin.com/v2/integrations/{uuid}/logs : a response with all logs for an integration. GET https://api.moltin.com/v2/integrations/{uuid}/jobs/{job_id} : a response with all logs for a given job. Each time an observable event occurs which you have an enabled integration observing, we create a job_id to use in the payload. You can see all jobs created via the https://api.moltin.com/v2/integrations/{uuid}/jobs subresource endpoint.

You can use that job_id to see the logs we generated for the notifications, for example, to return the logs for that specific event:

GET https://api.moltin.com/v2/integrations/{uuid}/jobs/{job_id}

Using the GET https://api.moltin.com/v2/integrations/{uuid}/logs endpoint gives you a stream of all job logs for a given integration.

Get all logs

Get a list of logs for all integrations.

curl https://api.moltin.com/v2/integrations/logs \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations/logs

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get the logs for an integration

Get a list of logs for an integration.

curl https://api.moltin.com/v2/integrations/{INTEGRATION_ID}/logs \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations/{INTEGRATION_ID}/logs

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
integration_id string The id for the integration requested.

Get the jobs for an integration

Get a list of jobs for an integration.

curl https://api.moltin.com/v2/integrations/{INTEGRATION_ID}/jobs \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations/{INTEGRATION_ID}/jobs

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
integration_id string The id for the integration requested.

Get the logs for a processed job by an integration

Get a list of jobs for an integration.

curl https://api.moltin.com/v2/integrations/{INTEGRATION_ID}/jobs/{JOB_ID}/logs \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/integrations/{INTEGRATION_ID}/jobs/{JOB_ID}/logs

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
integration_id string The id for the integration requested.
job_id string The id for the integration job you want logs for.

Inventory

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.

{
  "data": {
    "id": "75fbeab0-75a3-4d6b-b23b-9db7455c077e",
    "type": "stock",
    "total": 111,
    "available": 4
  }
}
Attribute Type Description
id string The unique identifier for this stock.
type string Represents the type of object being returned.
total integer The total amount of stock we have.
available integer The amount of stock available for purchase.

Get stock for all products

Get all stock.

curl -X GET https://api.moltin.com/v2/inventories \
     -H "Authorization: Bearer XXXX"

HTTP Request

GET /v2/inventories

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Query String

Attribute Type Description
page[limit] number Number of items to return per page
page[offset] number Item offset (used for pagination)

Get the stock for a product

Get all stock.

curl -X GET https://api.moltin.com/v2/inventories/{PRODUCT_ID} \
     -H "Authorization: Bearer XXXX"

HTTP Request

GET /v2/inventories/{PRODUCT_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
product_id string The id for the product requested.

The stock transaction object

{
  "data": {
    "id": "a4249924-9eed-4d7c-9ab5-13e308554e4d",
    "type": "stock-transaction",
    "action": "increment",
    "product_id": "75fbeab0-75a3-4d6b-b23b-9db7455c077e",
    "quantity": 7
  }
}
Attribute Type Description
id string The unique identifier for this stock transaction.
type string Represents the type of object being returned.
action string The type of action performed by this transaction: increment, decrement.
product_id string The product identifier that this transaction is for.
quantity integer The amount of stock affected by the transaction.

Get stock transactions for a product

Get all transactions for a product.

curl -X GET https://api.moltin.com/v2/inventories/{PRODUCT_ID}/transactions \
     -H "Authorization: Bearer XXXX"

HTTP Request

GET /v2/inventories/{PRODUCT_ID}/transactions

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
product_id string The id for the product requested.

Create a stock transaction for a product

curl -X POST https://api.moltin.com/v2/inventories/{PRODUCT_ID}/transactions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "type": "stock-transaction",
        "action": "increment",
        "quantity": 3
     }
}'

There are four types of transactions that can be applied to your stock:

HTTP Request

POST /v2/inventories/{PRODUCT_ID}/transactions

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
product_id string The id for the product requested.

Request Body

Attribute Type Description
type string Represents the type of object being returned. required
action string Type type of action you are performing on this stock: increment, decrement. required
quantity integer The amount of stock to affect with this transaction. optional

Orders

The order object

The order object is a representation of an order in moltin.

{
  "data": {
      "type": "order",
      "id": "6d809942-da51-4f07-9350-47fe759b2369",
      "status": "incomplete",
      "payment": "unpaid",
      "shipping": "unfulfilled",
      "customer": {
        "name": "Brad",
        "email": "brad@bobley.com"
      },
      "shipping_address": {
        "first_name": "Otis",
        "last_name": "Sedmak",
        "company_name": "Sedmak & Co.",
        "line_1": "1251, Rexmere Ave",
        "line_2": "Farmingville, Suffolk",
        "city": "shipping city",
        "postcode": "11738",
        "county": "Farmingville, Suffolk",
        "country": "US",
        "instructions": "Leave in porch"
      },
      "billing_address": {
        "first_name": "Jack",
        "last_name": "Macdowall",
        "company_name": "Macdowalls",
        "line_1": "1225 Invention Avenue",
        "line_2": "Birmingham",
        "city": "billing city",
        "postcode": "B21 9AF",
        "county": "West Midlands",
        "country": "US"
      },
      "links": {},
      "meta": {
        "display_price": {
          "with_tax": {
            "amount": 45598,
            "currency": "USD",
            "formatted": "$455.98"
          },
          "without_tax": {
            "amount": 45598,
            "currency": "USD",
            "formatted": "$455.98"
          }
        },
        "timestamps": {
          "created_at": "2017-09-25T14:13:18.738Z",
          "updated_at": "2017-09-25T14:13:18.738Z"
        }
      },
      "relationships": {
        "items": {
          "data": [
            {
              "type": "item",
              "id": "52a88bad-16c4-49ff-8684-089cec3e3f35"
            }
          ]
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "c8c1c511-beef-4812-9b7a-9f92c587217c"
          }
        }
      }
    }
}
Attribute Type Description
id string The unique identifier for this order.
type string Represents the type of object being returned. order.
status string incomplete, cancelled, complete.
payment string unpaid, authorized, not_applicable, paid.
shipping string fulfilled, unfulfilled.
customer object The customer object associated with this order.
customer.name string The customers name.
customer.email string The customers email.
shipping_address object The shipping address object.
shipping_address.first_name string The first name of the address holder. required
shipping_address.last_name string The last name of the address holder. required
shipping_address.company_name string The company name. optional
shipping_address.line_1 string First line of the address. required
shipping_address.line_2 string Second line of the address. optional
shipping_address.city string City. optional
shipping_address.postcode string Postcode or Zip Code of the address. required
shipping_address.county string County or State of the address. required
shipping_address.country string Country. required
shipping_address.instructions string Any instructions with the shipping address. optional
billing_address object The billing address object.
billing_address.first_name string The first name of the billing address holder. required
billing_address.last_name string The last name of the billing address holder. required
billing_address.company_name string The billing company name. optional
billing_address.line_1 string First line of the billing address. required
billing_address.line_2 string Second line of the billing address. optional
billing_address.city string City. optional
billing_address.postcode string Postcode or Zip Code of the billing address. required
billing_address.county string Country. required
billing_address.country string Any instructions with the shipping address. optional
links object A collection of URLs related to this resource.
meta object Additional information calculated for this order.
meta.display_price object A collection of fields related to the totals and currency of this order.
meta.display_price.
with_tax
object Tax inclusive totals.
meta.display_price.
with_tax.amount
integer The raw total of this order (inc tax).
meta.display_price.
with_tax.currency
string The currency set for this order.
meta.display_price.
with_tax.formatted
string The tax inclusive formatted total based on the currency.
meta.display_price.
without_tax
object Tax exclusive totals.
meta.display_price.
without_tax.amount
integer The raw total of this cart (ex tax).
meta.display_price.
without_tax.currency
string The currency set for this order.
meta.display_price.
without_tax.formatted
string The tax exclusive formatted total based on the currency.
meta.timestamps object Timestamps for this order.
meta.timestamps.
created_at
string The creation date of this order.
meta.timestamps.
updated_at
string The last updated date of this order.
relationships object A collection of relationships related to this resource.
relationships.items object The order items object.
relationships.items.data array An array of order items.
relationships.items.data.type string Represents the type of object being returned. item.
relationships.items.data.id string The unique identifier for this order item.
relationships.customer object The customer object.
relationships.customer.data object The customer object associated with this order.
relationships.customer.data.type string Represents the type of object being returned. customer.
relationships.customer.data.id string The unique identifier for this customer.

The order item object

{
  "data": {
    "id": "52a88bad-16c4-49ff-8684-089cec3e3f35",
    "type": "order_item",
    "product_id": "fc6122b9-de9d-4d08-9fa6-0f4a69459dc6",
    "name": "My Great Product",
    "sku": "MGP_001",
    "quantity": 4,
    "unit_price": {
      "amount": 7150,
      "currency": "USD",
      "includes_tax": true
    },
    "value": {
      "amount": 28600,
      "currency": "USD",
      "includes_tax": true
    },
    "links": {},
    "meta": {
      "display_price": {
        "with_tax": {
          "unit": {
            "amount": 7150,
            "currency": "USD",
            "formatted": "$71.50"
          },
          "value": {
            "amount": 28600,
            "currency": "USD",
            "formatted": "$286.00"
          }
        },
        "without_tax": {
          "unit": {
            "amount": 7150,
            "currency": "USD",
            "formatted": "$71.50"
          },
          "value": {
            "amount": 28600,
            "currency": "USD",
            "formatted": "$286.00"
          }
        }
      },
      "timestamps": {
        "created_at": "2017-09-25T14:13:18.738031028Z",
        "updated_at": "2017-09-25T14:13:18.738031028Z"
      }
    },
    "relationships": {
      "cart_item": {
        "data": {
          "type": "cart_item",
          "id": "56b18551-6baa-4e07-b3f7-19794359e962"
        }
      }
    }
  }
Attribute Type Description
id string The unique identifier for this order item.
type string Represents the type of object being returned. order_item
product_id string The unique identifier for the product for this order item.
name string Denotes the name of this order item.
sku string The SKU code for the order 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
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
relationships.cart_item object The customer object.
relationships.cart_item.data object The customer object associated with this order.
relationships.cart_item.data.type string Represents the type of object being returned. cart_item.
relationships.cart_item.data.id string The unique identifier for this cart item.

Order filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
status string eq eq(status,complete)
payment string eq eq(payment,paid)
shipping string eq eq(shipping,unfulfilled)
name (customer.name) string eq, like like(name,Brad*)
email (customer.email) string eq, like like(email,*@moltin.com)
customer_id (relationships.customer.data.id) string eq, like eq(customer_id,e5a0d684-a4af-4919-a348-f66b0b4955e0)
shipping_name (shipping.name) string eq, like like(shipping_name,home)
shipping_postcode (shipping.postcode) string eq, like like(shipping_postcode,117*)
billing_name (billing.name) string eq, like like(billing_name,home)
billing_postcode (billing.postcode) string eq, like like(billing_postcode,117*)
with_tax integer gt, ge, lt, le ge(with_tax,10000)
without_tax integer gt, ge, lt, le ge(without_tax,10000)
currency string eq eq(currency,USD)
product_id string eq eq(product_id,6837058c-ae42-46db-b3c6-7f01e0c34b40)
product_sku string eq eq(product_sku,deck-shoe-001)

Notes:

Get all orders

Get a list of all orders.

curl -X GET https://api.moltin.com/v2/orders \
  -H "Authorization: Bearer XXXX"
Moltin.Orders().All().then((orders) => {
  // Do something...
});

HTTP Request

GET /v2/orders

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Customer-Token string A customer token to access specific customer orders. optional

Query String

Attribute Type Description
filter string Filter the results

Get a single order

Get a single order.

curl -X GET https://api.moltin.com/v2/orders/{ORDER_ID} \
  -H "Authorization: Bearer XXXX"
Moltin.Orders().Get("{ORDER_ID}").then((orders) => {
  // Do something...
});

HTTP Request

GET /v2/orders/{ORDER_ID}

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.

Update an order

Update an order.

curl -X PUT https://api.moltin.com/v2/orders/{ORDER_ID} \
  -H "Authorization: Bearer XXXX"
  Not supported yet.

HTTP Request

PUT /v2/orders/{ORDER_ID}

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.
Attribute Type Description
shipping string fulfilled, unfulfilled. optional
shipping_address object The shipping address object.
shipping_address.first_name string The first name of the address holder. optional
shipping_address.last_name string The last name of the address holder. optional
shipping_address.company_name string The company name. optional
shipping_address.line_1 string First line of the address. optional
shipping_address.line_2 string Second line of the address. optional
shipping_address.city string City. optional
shipping_address.postcode string Postcode or Zip Code of the address. optional
shipping_address.county string County or State of the address. optional
shipping_address.country string Country. optional
shipping_address.instructions string Any instructions with the shipping address. optional

Get order items

curl -X GET https://api.moltin.com/v2/orders/{ORDER_ID}/items \
  -H "Authorization: Bearer XXXX"
  Not supported yet.

HTTP Request

GET /v2/orders/{ORDER_ID}/items

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!

Before accepting payments from your chosen gateway, you'll need to ensure you've configured and enabled it.

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.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/transactions/{TRANSACTION_ID}/capture \
     -H "Authorization: Bearer XXXX"
// Not supported

HTTP Request

POST /v2/orders/{ORDER_ID}/transactions/{TRANSACTION_ID}/capture

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 UUID of the order you want to capture
transaction_id string The UUID of the transaction that was previously authorized

Request Body

The request body for this request is empty.

Payment Gateways

Gateways provide access to external payment services. You cannot add new gateways, but you can enable or disable gateways we offer for you.

If you wish to circumvent payment gateways, you could choose to use the manual gateway.

Certain gateways have specific fields on them, check your gateway to see more detailed request, response fields.

The gateways object

The gateways object is a representation of a gateway in moltin.

{
  "data": {
    "enabled": false,
    "name": "Manual",
    "slug": "manual",
    "type": "gateway"
  }
}
Attribute Type Description
enabled boolean true if the gateway is enabled, false if disabled.
name string The name of the payment gateway.
slug string The slug of the payment gateway.
type string Represents the type of object being returned.

Get a list of supported gateways

Get a list of all supported gateways.

curl -X GET https://api.moltin.com/v2/gateways \
     -H "Authorization: Bearer XXXX"
Moltin.gateways.All().then((gateway) => {
  // Do something
});

HTTP Request

GET /v2/gateways

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get a gateway

Get a single gateway by slug.

curl -X GET https://api.moltin.com/v2/gateways/{GATEWAY_SLUG} \
     -H "Authorization: Bearer XXXX"
Moltin.gateways.Get("{GATEWAY_SLUG}").then((gateway) => {
  // Do something
});

HTTP Request

GET /v2/gateways/{GATEWAY_SLUG}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

URL Param Type Description
gateway_slug string The slug for the gateway requested.

Adyen

Configuring our Adyen integration.

The Adyen gateway object

{
  "data": {
    "enabled": true,
    "merchant_account": "xxx",
    "name": "Adyen",
    "password": "xxx",
    "slug": "adyen",
    "test": false,
    "type": "gateway",
    "username": "xxx"
  }
}
Attribute Type Description
enabled bool Enable or disable this gateway.
merchant_account string Your Adyen account name.
name string The display name of the gateway.
password string Your web service user password.
slug string A unique slug for this gateway.
test bool Whether to use test transactions or not.
type string This is a gateway object.
username string Your web service username.

Updating Adyen settings

Update your Adyen configuration.

curl -X PUT https://api.moltin.com/v2/gateways/adyen \
    -H "Authorization: Bearer XXX" \
    -d $'{
     "data": {
        "enabled": true
        "merchant_account": "xxx",
        "password": "xxx",
        "test": false,
        "username": "xxx"
     }
}'
    // Not supported

HTTP Request

PUT /v2/gateways/adyen

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
enabled boolean true if the gateway is enabled, false if disabled.
merchant_account string Your Adyen account name.
password string Your web service user password.
username string Your web service username.

Braintree

Configuring our Braintree integration.

The Braintree gateway object

{
  "data": {
    "enabled": true,
    "environment": "production",
    "merchant_id": "xxx",
    "name": "Braintree",
    "private_key": "xxx",
    "public_key": "xxx",
    "slug": "braintree",
    "type": "gateway"
  }
}
Attribute Type Description
enabled bool Enable or disable this gateway.
environment string production or sandbox.
merchant_id string Your Braintree merchant ID.
name string The display name of the gateway.
private_key string Your Braintree private key.
public_key string Your Braintree public key.
slug string A unique slug for this gateway.
type string This is a gateway object.

Updating Braintree settings

Update your Braintree configuration.

curl -X PUT https://api.moltin.com/v2/gateways/braintree \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "enabled": true,
        "environment": "production",
        "merchant_id": "xxx",
        "private_key": "xxx",
        "public_key": "xxx",
     }
}'
    // Not supported

HTTP Request

PUT /v2/gateways/braintree

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
enabled boolean true if the gateway is enabled, false if disabled.
environment string production or sandbox.
merchant_id string Your Braintree merchant ID.
private_key string Your Braintree private key.
public_key string Your Braintree public key.

Stripe

Configuring our Stripe integration.

The Stripe gateway object

{
  "data": {
    "enabled": true,
    "login": "xxx",
    "name": "Stripe",
    "slug": "stripe",
    "type": "gateway"
  }
}
Attribute Type Description
enabled bool Enable or disable this gateway.
login string Your Stripe secret key (test or live).
name string The display name of the gateway.
slug string A unique slug for this gateway.
type string This is a gateway object.

Updating Stripe settings

Update your Stripe configuration.

curl -X PUT https://api.moltin.com/v2/gateways/stripe \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": {
        "enabled": true,
        "login": "xxx"
     }
}'
    // Not supported

HTTP Request

PUT /v2/gateways/stripe

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
enabled boolean true if the gateway is enabled, false if disabled.
login string Your Stripe secret key (test or live).

Adyen Payments

Our Adyen integration currently supports:

Purchase Authorize Capture
Card Payment

Card Payment

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

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "adyen",
    "method": "purchase",
    "first_name": "John",
    "last_name": "Smith",
    "number": "4111111111111111",
    "month": "10",
    "year": "2020",
    "verification_value": "737"
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "adyen",
  method: "purchase",
  first_name: "John",
  last_name: "Smith",
  number: "4111111111111111",
  month: "10",
  year: "2020",
  verification_value: "737"
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

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 UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
first_name string The first name of the card owner
last_name string The last name of the card owner
number string The full card number
month string The expiry month of the card
year string The expiry year of the card
verification_value string The CVV/CVC code from the back of the card

Braintree Payments

Our Braintree integration currently supports:

Purchase Authorize Capture
Card Payment
Customer ID
Payment Method Token
Payment Method Nonce

Card Payment

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

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "braintree",
    "method": "purchase",
    "first_name": "John",
    "last_name": "Smith",
    "number": "4111111111111111",
    "month": "10",
    "year": "2020",
    "verification_value": "123"
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "braintree",
  method: "purchase",
  first_name: "John",
  last_name: "Smith",
  number: "4111111111111111",
  month: "10",
  year: "2020",
  verification_value: "123"
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

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 UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
first_name string The first name of the card owner
last_name string The last name of the card owner
number string The full card number
month string The expiry month of the card
year string The expiry year of the card
verification_value string The CVV/CVC code from the back of the card

Customer ID

This method allows you to bill a specific customer from Braintree. Braintree will bill the default billing method in the customers account.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "braintree",
    "method": "purchase",
    "payment": BRAINTREE_CUSTOMER_ID
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "braintree",
  method: "purchase",
  payment: BRAINTREE_CUSTOMER_ID
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

URL Parameters

URL Param Type Description
order_id string The UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
payment string The Braintree customer ID that you want to bill
options object Additional options for the request
options.custom_fields object Optional custom fields to send to Braintree. These fields must be configured in Braintree

Payment Method Token

This endpoint allows you to pay for an order with a specific Braintree Payment Method Token. This is similar to the Customer ID payment type, but you can define a specific payment source to charge.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "braintree",
    "method": "purchase",
    "payment": BRAINTREE_CUSTOMER_ID,
    "options": {
        "payment_method_token": BRAINTREE_PAYMENT_METHOD_TOKEN
    }
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "braintree",
  method: "purchase",
  payment: BRAINTREE_CUSTOMER_ID,
  options: {
      payment_method_token: BRAINTREE_PAYMENT_METHOD_TOKEN
  }
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

URL Parameters

URL Param Type Description
order_id string The UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
payment string The Braintree customer ID that you want to bill
options object Additional options for the request
options.payment_method_token string The payment method token to charge
options.custom_fields object Optional custom fields to send to Braintree. These fields must be configured in Braintree

Payment Method Nonce

This endpoint allows you to pay for an order with a previously created Braintree Payment Method Nonce.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "braintree",
    "method": "purchase",
    "payment": BRAINTREE_PAYMENT_NONCE,
    "options": {
        "payment_method_nonce": true
    }
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "braintree",
  method: "purchase",
  payment: BRAINTREE_PAYMENT_NONCE,
  options: {
      payment_method_nonce: true
  }
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

URL Parameters

URL Param Type Description
order_id string The UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
payment string The Braintree customer ID that you want to bill
options object Additional options for the request
options.payment_method_nonce bool Set this to true
options.custom_fields object Optional custom fields to send to Braintree. These fields must be configured in Braintree

Manual Gateway

Our manual gateway is a great way to start using moltin, even if we don't support the payment gateway you'd like to use yet. The manual gateway supports:

Purchase Authorize Capture
Manual Payment

Manual Payment

Manual payments must be authorized and then captured separately.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "manual",
    "method": "authorize",
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "manual",
  method: "authorize"
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

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 UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method

Stripe Payments

Our Stripe integration currently supports:

Purchase Authorize Capture
Card Payment
Stripe Token
Stripe Source

Card Payment

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

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "stripe",
    "method": "purchase",
    "first_name": "John",
    "last_name": "Smith",
    "number": "4242424242424242",
    "month": "10",
    "year": "2020",
    "verification_value": "123"
  }
}'
Moltin.Orders.Payment('orderId', {
  gateway: "stripe",
  method: "purchase",
  first_name: "John",
  last_name: "Smith",
  number: "4242424242424242",
  month: "10",
  year: "2020",
  verification_value: "123"
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

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 UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
first_name string The first name of the card owner
last_name string The last name of the card owner
number string The full card number
month string The expiry month of the card
year string The expiry year of the card
verification_value string The CVV/CVC code from the back of the card

Stripe Sources & Tokens

This request allows you to pay for an order using Stripe and token or source.

curl -X POST https://api.moltin.com/v2/orders/{ORDER_ID}/payments \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "gateway": "stripe",
    "method": "purchase",
    "payment": "tok_visa"
  }
}'
Moltin.Orders.Payment("orderId", {
  gateway: "stripe",
  method: "purchase",
  payment: "tok_visa"
}).then(() => {
  // Do something
});

HTTP Request

POST /v2/orders/{ORDER_ID}/payments

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 UUID of the order you want to pay for

Request Body

Name Type Description
gateway string The gateway you want to use for this payment
method string The payment method
payment string The Stripe token or source you want to charge

Products

Products are the goods you sell from your store and can be managed via the API. They can be added to a cart, they can be categorized and associated with brands or collections.

The product object

{
  "data": {
    "type": "product",
    "id": "6837058c-ae42-46db-b3c6-7f01e0c34b40",
    "name": "Deck Shoe",
    "slug": "deck-shoe",
    "sku": "deck-shoe-001",
    "manage_stock": true,
    "description": "Modern boat shoes were invented in 1935 by American Paul A. Sperry of New Haven, Connecticut after noticing his dog's ability to run easily over ice without slipping. Using a knife, he cut siping into his shoes' soles, inspiring a shoe perfect for boating and a company called Sperry Top-Sider.",
    "price": [
      {
        "amount": 5891,
        "currency": "USD",
        "includes_tax": true
      }
    ],
    "status": "live",
    "commodity_type": "physical",
    "meta": {
      "timestamps": {
        "created_at": "2017-08-25T09:36:14+00:00",
        "updated_at": "2017-08-25T09:36:14+00:00"
      },
      "display_price": {
        "with_tax": {
          "amount": 5891,
          "currency": "USD",
          "formatted": "$58.91"
        },
        "without_tax": {
          "amount": 5891,
          "currency": "USD",
          "formatted": "$58.91"
        }
      },
      "stock": {
        "level": 31,
        "availability": "in-stock"
      },
      "variation_matrix": []
    },
    "relationships": {
        "categories": {
            "data": [
                {
                    "type": "category",
                    "id": "8550c943-85c2-4239-a8a4-bfa255a38f08"
                }
            ]
        },
        "brands": {
            "data": [
                {
                    "type": "brand",
                    "id": "c2c16959-5dfa-4ce8-a122-28523c04c0a2"
                }
            ]
        },
        "collections": {
            "data": [
                {
                    "type": "collection",
                    "id": "ced85f3a-f1d2-47b5-ada5-bcbc43eb59eb"
                }
            ]
        },
        "files": {
            "data": [
                {
                    "type": "file",
                    "id": "f1a384bc-e77b-4fe7-9cdd-ec82095f2769"
                }
            ]
        },
        "main_image": {
            "data": {
                "type": "main_image",
                "id": "54ef64a7-8a43-4398-acf2-66aa3c038136"
            }
        }
    }
  }
}
Attribute Type Description
id string The unique identifier for this product
type string Represents the type of object being returned (should be product)
name string A human readable name for this product
slug string A human readable slug value. Must be unique
sku string SKU value. Must be unique
manage_stock boolean true if moltin should manage stock, false if not. See inventory
description string A human readable description of the product
price array An array of prices for this product in different currencies
price.amount integer Value of the price in the lowest denomination for that currency
price.currency string Currency code of this price (3 letter ISO)
price.includes_tax boolean true if relevant taxes have been included in the price false if not
status string Whether this product is draft or live
commodity_type string Is this a physical or digital product
meta object Additional information calculated for this product
meta.timestamps object Timestamps for this product
meta.timestamps.
created_at
string The creation date of this product
meta.timestamps.
updated_at
string The last updated date of this product
meta.stock object Stock information for this product
meta.stock.
level
integer The stock level for this product
meta.stock.
availability
string in-stock / out-stock
meta.display_price object Formatted display prices based on the currency settings for this request
meta.display_price.
with_tax
object Tax inclusive prices for this product
meta.display_price.
with_tax.amount
integer The raw total of this product (inc tax)
meta.display_price.
with_tax.currency
string The currency this display price has been formatted for
meta.display_price.
with_tax.formatted
string The tax inclusive formatted total based on the currency
meta.display_price.
without_tax
object Tax exclusive totals
meta.display_price.
without_tax.amount
integer The raw total of this product (ex tax)
meta.display_price.
without_tax.currency
string The currency this display price has been formatted for
meta.display_price.
without_tax.formatted
string The tax exclusive formatted total based on the currency
meta.variations array An array of variations attached to this product
meta.variations.id string The variation ID
meta.variations.name string The variation name
meta.variations.options array An array of options attached to this variation
meta.variations.options.id string The option ID
meta.variations.options.name string The option name
meta.variations.options.description string A description of the option
meta.variation_matrix object A matrix of option IDs to child product IDs. This information is only returned when getting a product by ID
relationships object Relationships to other resources
relationships.
variations
object Relationships information regarding variations for this product (hidden if no variation relationships exist)
relationships.
variations.data
array An array of relationships from this product to variation resources
relationships.
variations.data.type
string Will always be product-variation
relationships.
variations.data.id
id The id of the related variation
relationships.
files
object Relationships information regarding files for this product (hidden if no file relationships exist)
relationships.
files.data
array An array of relationships from this product to file resources
relationships.
files.data.type
string Will always be file
relationships.
files.data.id
id The id of the related file
relationships.
main_image
object Relationships information regarding main_image for this product (hidden if no main_image relationships exist)
relationships.
main_image.data
object An relationship from this product to a file resource
relationships.
main_image.data.type
string Will always be main_image
relationships.
main_image.data.id
id The id of the related file
relationships.
categories
object Relationships information regarding categories for this product (hidden if no category relationships exist)
relationships.
categories.data
array An array of relationships from this product to category resources
relationships.
categories.data.type
string Will always be category
relationships.
categories.data.id
id The id of the related category
relationships.
collections
object Relationships information regarding collections for this product (hidden if no collection relationships exist)
relationships.
collections.data
array An array of relationships from this product to category resources
relationships.
collections.data.type
string Will always be collection
relationships.
collections.data.id
id The id of the related collection
relationships.
brands
object Relationships information regarding brands for this product (hidden if no brand relationships exist)
relationships.
brands.data
array An array of relationships from this product to brand resources
relationships.
brands.data.type
string Will always be brand
relationships.
brands.data.id
id The id of the related brand

Product filtering

The following attributes are available to filter by:

Attribute Type Acceptable Operators Example
name string eq, like like(name,Deck*)
slug string eq, like eq(slug,deck-shoe)
sku string eq, like eq(sku,deck-shoe-001)
status string eq, like eq(status,live)
description string like like(description,*deck*)
manage_stock boolean eq eq(manage_stock,true)
commodity_type string eq, like eq(commodity_type,digital)

Get a list of products

Get a list of all products.

Get a list of products.

curl -X GET https://api.moltin.com/v2/products \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -H "X-MOLTIN-LANGUE: en"
Moltin.Products.All().then((products) => {
    // Do something
});

HTTP Request

GET /v2/products

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Currency string A currency code enabled on the store. This designates how display_price properties will be formatted.
X-Moltin-Language string A language defined in the store settings to display any available translation in that language - if no translation exists the default name and title will be returned.

Query String

Attribute Type Description
page[offset] number Item offset (used for pagination)
page[limit] number Number of items to return per page
sort string Attributes by which to sort the query, prepend with a minus to reverse
filter string Filter the results
include string main_image,files,brands,categories,collections

Create a product

Create a new product.

curl -X POST https://api.moltin.com/v2/products \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "product",
    "name": "Deck Shoe",
    "slug": "deck-shoe",
    "sku": "deck-shoe-001",
    "description": "Modern boat shoes were invented in 1935 by American Paul A. Sperry",
    "manage_stock": true,
    "price": [
      {
        "amount": 5891,
        "currency": "USD",
        "includes_tax": true
      }
    ],
    "status": "live",
    "commodity_type": "physical"
  }
}'
var product = {
    type: "product",
    name: "Deck Shoe",
    slug: "deck-shoe",
    sku: "deck-shoe-001",
    description: "A product for testing purposes",
    manage_stock: false,
    price: [
        {
            amount: 5891,
            currency: "USD",
            includes_tax: true
        }
    ],
    status: "live",
    commodity_type: "physical"
};

Moltin.Products.Create(product).then((product) => {
  // Do something
});

HTTP Request

POST /v2/products

HTTP Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Attribute Type Description
type string Represents the type of object being created (should be product). required
name string A human readable name for this product. required
slug string A unique slug for this product. required
sku string A unique SKU for this product. required
manage_stock boolean true if moltin should manage stock, false if not. required
description string A human readable description of the product. required
price array An array of prices, one for each currency. required
price.amount integer Value of the price
price.currency string Currency of this price (3 letter ISO)
price.includes_tax boolean true if relevant taxes have been included in the price false if not
status string draft / live. required
commodity_type string physical/digital

Get a product

Get a single product by id.

curl https://api.moltin.com/v2/products/{PRODUCT_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -H "X-Moltin-Language: en"
Moltin.Products.Get('{PRODUCT_ID}').then((product) => {
    // Do something
});

HTTP Request

GET /v2/products/{PRODUCT_ID}

URL Parameters

URL Param Type Description
product_id string The id of the product requested

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Currency string The code for the currency that display_price should be formatted for
X-Moltin-Language string A language defined in the store settings to display any available translation in that language - if no translation exists the default name and title will be returned.

Query String

Attribute Type Description
include string main_image,files,brands,categories,collections, children, parent

Update a product

Update an existing product.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -H "X-Moltin-Language: en" \
     -d $'{
  "data": {
    "type": "product",
    "id": "{PRODUCT_ID}",
    "name": "Updated product name"
  }
}'
var product = {
    "type": "product",
    "id": "{PRODUCT_ID}",
    "name": "Updated product name"
};

Moltin.Products.Update("{PRODUCT_ID}", data).then((product) => {
  // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}

URL Parameters

URL Param Type Description
product_id string The ID of the product you wish to update

HTTP Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required
X-Moltin-Language string If set, the system will store a record of the translation in the specified language.

Request Body

Attribute Type Description
type string Represents the type of object being created (should be product). required
name string A human readable name for this product. required
slug string A unique slug for this product. required
sku string A unique SKU for this product. required
manage_stock boolean true if moltin should manage stock, false if not
description string A human readable description of the product
price array An array of prices, one for each currency
price.amount integer Value of the price
price.currency string Currency of this price (3 letter ISO)
price.includes_tax boolean true if relevant taxes have been included in the price false if not
status string draft / live
commodity_type string physical/digital

Delete a product

Delete a product by id.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Moltin.Products.Delete("{PRODUCT_ID}").then((product) => {
  // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to delete

Product Relationships

Create Brand Relationship(s)

Create a product relationship to one or more brand. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/brands \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    },
    {
      "type": "brand",
      "id": "1334e667-7b2b-4159-9e36-8a3b404901c8"
    }
  ]
}'
var brandIds = [
    '8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c',
    '1334e667-7b2b-4159-9e36-8a3b404901c8'
];

Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'brand', brandIds).then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/brands

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the brand(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be brand)
id string The id of the brand

Update Brand Relationship(s)

Replace the relationships between a product and a brand. Unlike a POST to this endpoint, a PUT overrides any existing relationships.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/brands \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    }
  ]
}'
var brandIds = [
    '8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c'
];

Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'brand', brandIds).then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/brands

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the brand(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be brand)
id string The id of the brand

Delete Brand Relationship(s)

Removing a relationship between a product and brand(s) deletes the relationships specified in the payload.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/brands \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "brand",
      "id": "8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c"
    }
  ]
}'
var brandIds = [
    '8a43aea7-79f0-4bcf-9bc8-a0f5d3d3642c'
];

Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'brand', brandIds).then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/brands

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the brand(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be brand)
id string The id of the brand

Create Category Relationship(s)

Create a product relationship to one or more category. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/categories \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "39a13b7e-f2d3-47a5-9bc5-1e98b198748c"
    },
    {
      "type": "category",
      "id": "0c108707-bb4a-4eda-95e3-f51b35122cb4"
    }
  ]
}'
var categoryIds = [
    '39a13b7e-f2d3-47a5-9bc5-1e98b198748c',
    '0c108707-bb4a-4eda-95e3-f51b35122cb4'
];

Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'category', categoryIds).then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/categories

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the category(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be category)
id string The id of the category

Update Category Relationship(s)

Replace the relationships between a product and a category. Unlike a POST to this endpoint, a PUT overrides any existing relationships.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/categories \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "d7290481-8d03-4fe0-a7df-23fc05498a46"
    }
  ]
}'
var categoryIds = [
    'd7290481-8d03-4fe0-a7df-23fc05498a46'
];

Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'category', categoryIds).then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/categories

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the category(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be category)
id string The id of the category

Delete Category Relationship(s)

Removing a relationship between a product and category(s) deletes the relationships specified in the payload.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/categories \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "category",
      "id": "0c108707-bb4a-4eda-95e3-f51b35122cb4"
    }
  ]
}'
var categoryIds = [
    '0c108707-bb4a-4eda-95e3-f51b35122cb4
];

Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'category', categoryIds).then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/categories

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the category(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be category)
id string The id of the category

Create Collection Relationship(s)

Create a product relationship to one or more collection. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/collections \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "5ab3deca-1f11-47b7-a409-24ea3234d72c"
    },
    {
      "type": "collection",
      "id": "2c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var collectionIds = [
    '5ab3deca-1f11-47b7-a409-24ea3234d72c',
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'collection', collectionIds).then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/collections

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the collection(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be collection)
id string The id of the collection

Update Collection Relationship(s)

Replace the relationships between a product and a collection. Unlike a POST to this endpoint, a PUT overrides any existing relationships.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/collections \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "2c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var collectionIds = [
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'collection', collectionIds).then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/collections

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the collection(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be collection)
id string The id of the collection

Delete Collection Relationship(s)

Removing a relationship between a product and collection(s) deletes the relationships specified in the payload.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/collections \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "collection",
      "id": "2c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var collectionIds = [
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'collection', collectionIds).then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/collections

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the collection(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be collection)
id string The id of the collection

Create File Relationship(s)

Create a product relationship to one or more file. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/files \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "file",
      "id": "82c51711-35f9-403e-aa73-8e6c80c2258b"
    },
    {
      "type": "file",
      "id": "c090e3c8-0206-4243-9a3b-f28175f7e9de"
    }
  ]
}'
var fileIds = [
    '82c51711-35f9-403e-aa73-8e6c80c2258b',
    'c090e3c8-0206-4243-9a3b-f28175f7e9de'
];

Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'file', fileIds).then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/files

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the file(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be file)
id string The id of the file

Update File Relationship(s)

Replace the relationships between a product and a file. Unlike a POST to this endpoint, a PUT overrides any existing relationships.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/files \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "file",
      "id": "82c51711-35f9-403e-aa73-8e6c80c2258b"
    }
  ]
}'
var fileIds = [
    '82c51711-35f9-403e-aa73-8e6c80c2258b'
];

Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'file', fileIds).then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/files

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the file(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be file)
id string The id of the file

Delete File Relationship(s)

Removing a relationship between a product and file(s) deletes the relationships specified in the payload.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/files \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "file",
      "id": "82c51711-35f9-403e-aa73-8e6c80c2258b"
    }
  ]
}'
var fileIds = [
    '82c51711-35f9-403e-aa73-8e6c80c2258b'
];

Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'file', fileIds).then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/files

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the file(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be file)
id string The id of the file

Create a Main Image Relationship

Create a product relationship to a single file, which can be used as a main_image. You can only have one main image relationship

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/main-image \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "main_image",
    "id": "98df7738-febe-4987-bc0e-b857297b30e9"
  }
}'
Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'main_image', '98df7738-febe-4987-bc0e-b857297b30e9').then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/main-image

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the image

Request Body

Attribute Type Description
type string Represents the type of object (should be main_image)
id string The id of the image

Update a Main Image Relationship

Update the main image relationship. This will replace any currently related image.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/main-image \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "main_image",
    "id": "e9737dc6-876a-4eab-b3b7-af62a1999123"
  }
}'
Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'main_image', 'e9737dc6-876a-4eab-b3b7-af62a1999123').then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/main-image

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the image

Request Body

Attribute Type Description
type string Represents the type of object (should be main_image)
id string The id of the image

Delete a Main Image Relationship

Delete the main image relationship. This will remove the related main image.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/main-image \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "main_image",
    "id": "e9737dc6-876a-4eab-b3b7-af62a1999123"
  }
}'
Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'main_image', 'e9737dc6-876a-4eab-b3b7-af62a1999123').then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/main-image

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to remove the relationship for

Request Body

Attribute Type Description
type string Represents the type of object (should be main_image)
id string The id of the image

Create Variations Relationship(s)

Create a product relationship to one or more variation. If any relationships already exist, the one's made in the request will be added to them.

curl -X "POST" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/variations \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "variation",
      "id": "3ab3deca-1f11-47b7-a409-24ea3234d72c"
    },
    {
      "type": "variation",
      "id": "7c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var variationIds = [
    '5ab3deca-1f11-47b7-a409-24ea3234d72c',
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.CreateRelationships('{PRODUCT_ID}', 'product-variation', variationIds).then((relationships) => {
    // Do something
});

HTTP Request

POST /v2/products/{PRODUCT_ID}/relationships/variations

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the variation(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be product-variation)
id string The id of the product-variation

Update Variation Relationship(s)

Replace the relationships between a product and a variation. Unlike a POST to this endpoint, a PUT overrides any existing relationships.

curl -X "PUT" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/variations \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "variation",
      "id": "2c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var variationIds = [
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.UpdateRelationships('{PRODUCT_ID}', 'variation', variationIds).then((relationships) => {
    // Do something
});

HTTP Request

PUT /v2/products/{PRODUCT_ID}/relationships/variations

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the collection(s)

Request Body

Attribute Type Description
type string Represents the type of object (should be variation)
id string The id of the variation

Delete Variation Relationship(s)

Removing a relationship between a product and variation(s) deletes the relationships specified in the payload.

curl -X "DELETE" https://api.moltin.com/v2/products/{PRODUCT_ID}/relationships/variations \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": [
    {
      "type": "variation",
      "id": "2c740aa0-7fb7-4bd6-9347-78988cf60f9a"
    }
  ]
}'
var variationIds = [
    '2c740aa0-7fb7-4bd6-9347-78988cf60f9a'
];

Moltin.Products.DeleteRelationships('{PRODUCT_ID}', 'variation', variationIds).then((relationships) => {
    // Do something
});

HTTP Request

DELETE /v2/products/{PRODUCT_ID}/relationships/variations

URL Parameters

URL Param Type Description
product_id string The id of the product you wish to relate to the variation(s)

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

{
    "data": {
        "type": "product-variation",
        "id": "f78b116b-fdf1-4546-b91b-764673697a96",
        "name": "Design",
        "relationships": {
            "options": {
                "data": [
                    {
                        "type": "option",
                        "id": "6885411e-4181-4b13-b828-b0be4b3cb307"
                    },
                    {
                        "type": "option",
                        "id": "8b360d0a-1977-4d6f-b2dc-930a4bac66ef"
                    },
                    {
                        "type": "option",
                        "id": "659cddbe-7532-4afd-beab-9eb4ff570e1c"
                    }
                ]
            }
        }
    },
    "included": {
        "options": [
            {
                "type": "option",
                "id": "6885411e-4181-4b13-b828-b0be4b3cb307",
                "name": "Flat",
                "description": "Flat",
                "relationships": {
                    "data": [
                        {
                            "type": "modifier",
                            "id": "810ec2ec-2e6f-436d-b101-3481e79a5a09"
                        },
                        {
                            "type": "modifier",
                            "id": "c5297c04-c625-4f57-9d61-c861424abaa5"
                        }
                    ]
                }
            },
            {
                "type": "option",
                "id": "8b360d0a-1977-4d6f-b2dc-930a4bac66ef",
                "name": "Geometric",
                "description": "Geometric",
                "relationships": {
                    "data": [
                        {
                            "type": "modifier",
                            "id": "c0ccd925-ad5d-4f91-878c-99fdb2502bec"
                        },
                        {
                            "type": "modifier",
                            "id": "a73962da-f4f1-46f0-8fa8-da3fdc57a96c"
                        }
                    ]
                }
            },
            {
                "type": "option",
                "id": "659cddbe-7532-4afd-beab-9eb4ff570e1c",
                "name": "Raster",
                "description": "Raster",
                "relationships": {
                    "data": [
                        {
                            "type": "modifier",
                            "id": "da414bba-0c6a-4647-8fe2-eaec51b41196"
                        },
                        {
                            "type": "modifier",
                            "id": "b73962da-f4f1-46f0-8fa8-da3fdc57a96c"
                        }
                    ]
                }
            }
        ],
        "modifiers": [
            {
                "id": "810ec2ec-2e6f-436d-b101-3481e79a5a09",
                "type": "modifier",
                "modifier_type": "sku_builder",
                "value": {
                    "seek": "DESIGN",
                    "set": "FLT"
                }
            },
            {
                "id": "c5297c04-c625-4f57-9d61-c861424abaa5",
                "type": "modifier",
                "modifier_type": "slug_append",
                "value": "-flat"
            },
            {
                "id": "c0ccd925-ad5d-4f91-878c-99fdb2502bec",
                "type": "modifier",
                "modifier_type": "sku_builder",
                "value": {
                    "seek": "DESIGN",
                    "set": "GEO"
                }
            },
            {
                "id": "a73962da-f4f1-46f0-8fa8-da3fdc57a96c",
                "type": "modifier",
                "modifier_type": "slug_append",
                "value": "-geometric"
            },
            {
                "id": "da414bba-0c6a-4647-8fe2-eaec51b41196",
                "type": "modifier",
                "modifier_type": "sku_builder",
                "value": {
                    "seek": "DESIGN",
                    "set": "RASTR"
                }
            },
            {
                "id": "b73962da-f4f1-46f0-8fa8-da3fdc57a96c",
                "type": "modifier",
                "modifier_type": "slug_append",
                "value": "-raster"
            }
        ]
    }
}
Attribute Type Description
id string The unique identifier for this variation
type string Represents the type of object being returned (should be product-variation)
name string A human readable name for this variation
relationships object Relationships to other resources
relationships
.options
object Relationships information regarding options for this variation
relationships
.options.data
array An array of relationships from this variation to options
relationships
.options.data.id
string The unique identifier for the option
relationships
.options.data.type
string The type (option)
included object Included resources
included
.options
array Array of options that constitute the variation
included
.options.id
string The unique identifier for the option
included
.options.type
string Represents the type of object (option)
included
.options.name
string A human readable name for the option
included
.options.description
string A human readable description for the option
included
.options.relationships
object Relationships to other resources
included
.options.relationships
.data
array An array of relationships from this option to modifiers
included
.options.relationships
.data.id
string The unique identifier for the modifier
included
.options.relationships
.data.type
string The type (modifier)
included
.modifiers
array Array of modifiers that constitute the variation options
included
.modifiers.id
string The unique identifier for the modifier
included
.modifiers.type
string The type (modifier)
included
.modifiers.modifier_type
string One of the modifier types available ADD LINK
included
.modifiers.value
mixed Value the modifier type allows ADD LINK

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.

Get Product Variations

curl -X GET https://api.moltin.com/v2/variations \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

This endpoint will allow you to retrieve all product-variations

HTTP Request

GET /v2/variations

Create a Product Variation

curl -X POST https://api.moltin.com/v2/variations \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "product-variation",
    "name": "Paint colour"
  }
}'
Not supported yet

POST to this endpoint in order to create a new product variation.

HTTP Request

POST /v2/variations

Attribute Type Description
type string Represents the type of object being created (should be product-variation)
name string A human readable name for this variation

Get a Product Variation

curl -X GET https://api.moltin.com/v2/variations/{VARIATION_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

Use this endpoint to retrieve a single product variation.

HTTP Request

GET /v2/variations/{VARIATION_ID}

URL Parameters

URL Param Type Description
variation_id string The id for the variation requested

Query String

Attribute Type Description
include string options TODO CHECK THIS

Update a Product Variation

curl -X PUT https://api.moltin.com/v2/variation/{VARIATION_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "product-variation",
    "id": "{VARIATION_ID}",
    "name": "Color schemes"
  }
}'
Not supported yet

The endpoint allows you to update an existing product variation.

HTTP Request

PUT /v2/variations/{VARIATION_ID}

URL Parameters

URL Param Type Description
variation_id string The id of the variation you wish to update

Request Body

Attribute Type Description
id string The id of the variation being updated
type string Represents the type of object being created (should be product-variation)
name string A human readable name for this variation

Delete a Product Variation

curl -X DELETE https://api.moltin.com/v2/variation/{VARIATION_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

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

HTTP Request

DELETE /v2/variations/{VARIATION_ID}

URL Parameters

URL Param Type Description
variation_id string The id of the variation you wish to delete

Build child products

curl -X POST https://api.moltin.com/v2/products/{PRODUCT_ID}/build \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

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.

The Product Variation Option object

{
    "type": "option",
    "id": "67af507f-e901-4647-a265-3aa931382959",
    "name": "Red",
    "description": "Red"
}

A variation option represents a option for selection for a single product-variation. For example, if your variation is "color", you may have three possible options red, green, and blue.

Attribute Type Description
id string The unique identifier for this option
type string Represents the type of object being returned (should be option)
name string A human readable name for this option
description string A human readable description of the product-variation-object
modifiers array An array of modifiers objects belonging to this variation option. See the modifiers section for further info

Create a Product Variation Option

curl -X POST https://api.moltin.com/v2/variations/{VARIATION_ID}/options \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "option",
    "name": "Blue",
    "description": "Our most popular color"
  }
}'
Not supported yet

POST to this endpoint in order to create a new product variation option.

HTTP Request

POST /v2/variations/{VARIATION_ID}/options

URL Parameters

URL Param Type Description
variation_id string The id of the variation belonging to this option

Request Body

Attribute Type Description
type string Represents the type of object being created (should be option)
name string A human readable name for this variation option
description string A human readable description of the option

Update a Product Variation Option

curl -X PUT https://api.moltin.com/v2/variations/{VARIATION_ID}/option/{OPTION_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "option",
    "id": "{OPTION_ID}",
    "name": "Red"
  }
}'
Not supported yet

The endpoint allows you to update an existing option.

HTTP Request

PUT /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 updated

Request Body

Attribute Type Description
id string The id of the option being updated
type string Represents the type of object being created (should be option)
name string A human readable name for this variation option
description string A human readable description of the variation option

Delete a Product Variation Option

curl -X DELETE https://api.moltin.com/v2/variation/{VARIATION_ID}/option/{OPTION_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

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.

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.

The builder is worthy of a brief example...

BaseProduct SKU: BP01-{COLOUR}-{SIZE}\ Modifier1:{"seek":"COLOUR", "set":"BLU"}\ Modifier2:{"seek":"COLOUR", "set":"RED"}

ModifierA:{"seek":"SIZE", "set":"LRG"}\ ModifierB:{"seek":"SIZE", "set":"SML"}

The above modifiers applied via variations for size and colour would produce the following SKUs in the corresponding variation product:

BP01-BLU-LRG\ BP01-BLU-SML\ BP01-RED-LRG\ BP01-RED-SML

You could create the same via sku_append modifier using values like -RED and -LRG, the advantage of the builder modifiers is that they are agnostic of the order the modifiers are applied.

The Product Modifier objects

Price modifiers

{
  "type": "modifier",
  "id": "6d31b2d1-6a26-47e5-9ea0-96b392490ab7",
  "modifier_type": "price_increment",
  "value": [
    {
      "currency": "FJT",
      "amount": 46008803,
      "includes_tax": false
    },
    {
      "currency": "YZK",
      "amount": 4011039,
      "includes_tax": false
    }
  ]
}
Attribute Type Description
id string The unique identifier for this product
type string Represents the type of object (should be modifier)
modifier_type string price_increment, price_decrement, price_equals
value.amount integer Value of the price modifier
value.currency string Currency of this price modifier (3 letter ISO)
value.includes_tax boolean true if relevant taxes have been included in the value false if not

SKU builder modifiers

{
  "type": "modifier",
  "id": "6d31b2d1-6a26-47e5-9ea0-96b392490ab7",
  "modifier_type": "sku-builder",
  "value": {
    "seek": "{PLACEHOLDER}",
    "set": "SKU001-",
  }
}
Attribute Type Description
id string The unique identifier for this product
type string Represents the type of object (should be modifier)
modifier_type string sku-builder, slug_builder TODO: Check for - / _ consistency
value.seek string A search string for the find / replace
value.set string Replacement string

Field override modifiers

{
  "type": "modifier",
  "id": "6d31b2d1-6a26-47e5-9ea0-96b392490ab7",
  "modifier_type": "name_equals",
  "value": "Overrode product name"
}
Attribute Type Description
id string The unique identifier for this product
type string Represents the type of object (should be modifier)
modifier_type string description_equals, description_prepend, description_append, commoditytype, name_equals, name_prepend, name_append, slug_equals, slug_prepend, slug_append, sku_equals, sku_prepend, sku_append, status
value string A string to be used in place of the product property

Create a new Product Modifier

curl -X "POST" https://api.moltin.com/v2/variations/{VARIATION_ID}/options/{OPTION_ID}/modifiers \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "modifier",
    "id": "6d31b2d1-6a26-47e5-9ea0-96b392490ab7",
    "modifier_type": "name_equals",
    "value": "Promotional product"
  }
}'
Not supported yet

Post here to create a new product modifier.

HTTP Request

POST /v2/variations/{VARIATION_ID}/options/{OPTION_ID}/modifiers

URL Parameters

URL Param Type Description
variation_id string The id of the variation belonging to this modifier
option_id string The id of the option belonging to the modifier

Request Body

Attribute Type Description
type string Represents the type of object being created (should be modifier)
modifier_type string price_increment, price_decrement, price_equals, sku-builder, slug_builder, description_equals, description_prepend, description_append, commoditytype, name_equals, name_prepend, name_append, slug_equals, slug_prepend, slug_append, sku_equals, sku_prepend, sku_append, status
value string/object A payload specific to the type of modifier (refer to the examples above)

Update a Product Modifier

curl -X "POST" https://api.moltin.com/v2/variations/{VARIATION_ID}/options/{OPTION_ID}/modifiers/{MODIFIER_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819" \
     -d $'{
  "data": {
    "type": "modifier",
    "id": "6d31b2d1-6a26-47e5-9ea0-96b392490ab7",
    "value": "Updated product name"
  }
}'
Not supported yet

The endpoint allows you to update an existing product modifier.

HTTP Request

PUT /v2/variations/{VARIATION_ID}/options/{OPTION_ID}/modifiers/{MODIFIER_ID}

URL Parameters

URL Param Type Description
variation_id string The id of the variation belonging to this modifier
option_id string The id of the option belonging to the modifier
modifier_id string The id of the modifier to be updated

Request Body

Attribute Type Description
id string The unique identifier for this modifier
type string Represents the type of object being updated (should be modifier)
modifier_type string price_increment, price_decrement, price_equals, sku-builder, slug_builder, description_equals, description_prepend, description_append, commoditytype, name_equals, name_prepend, name_append, slug_equals, slug_prepend, slug_append, sku_equals, sku_prepend, sku_append, status TODO: Check if it's possible to switch modifier types??
value string/object A payload specific to the type of modifier (refer to the examples above)

Delete a Product Modifier

curl -X "DELETE" https://api.moltin.com/v2/variation/{VARIATION_ID}/option/{OPTION_ID}/modifiers/{MODIFIER_ID} \
     -H "Authorization: Bearer 965baf46f390879c213e48cf84dcda16bb6d0819"
Not supported yet

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

HTTP Request

DELETE /v2/variations/{VARIATION_ID}/options/{OPTION_ID}/modifiers/{MODIFIER_ID}

URL Parameters

URL Param Type Description
variation_id string The id of the variation belonging to this modifier
option_id string The id of the option belonging to the modifier
modifier_id string The id of the modifier to be deleted

Promotions

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 promotion object

{
  "data": {
    "type": "promotion",
    "id": "15bf00b3-436b-446d-bda9-c021e4e4752b",
    "name": "Promo #1",
    "description": "Initial Promotion",
    "enabled": true,
    "promotion_type": "fixed_discount",
    "schema": {
      "currencies": [
        {
          "currency": "USD",
          "amount": 900
        },
        {
          "currency": "GBP",
          "amount": 1100
        }
      ]
    },
    "start": "2017-05-12T15:04:05Z",
    "end": "2019-10-12T15:04:05Z",
    "created_at": "2017-11-13T03:00:35.381148442Z",
    "updated_at": "2017-11-13T03:00:35.381148514Z"
  }
}

A promotion is represented by a promotion object.

Name Type Description
type string "promotion"
name string The name of your promotion.
description string A description of your promotion.
enabled boolean true if enabled, false if not.
promotion_type string One of: fixed_discount, percentage_discount.
schema object One of: fixed_schema, percent_schema
start string The start time of the promotion DateTime.
end string The end time of the promotion DateTime.

The schema object

moltin offer different types of promotion all defined by a schema. These schemas are used internally to verify a promotion and calculate a discount.

Below is the list of currently available promotion type schemas - these are to be used in the create promotion request.

Fixed Discount

"schema": {
  "currencies": [
    {
      "currency": "GBP",
      "amount": 1100
    }
  ]
}

Fixed discount provides a method to give a fixed discount to a cart.

Name Type Description
currencies array An array of objects.
currencies[].currency string A currency code.
currencies[].amount integer The amount to discount by.

Percentage Discount

  "schema": {
    "currencies": [
      {
        "currency": "GBP",
        "percentage": 12.5
      }
    ]
  }

Percentage discount provides a method to give a percentage discount to a cart based on the value of cart_items and custom_items.

Name Type Description
currencies array An array of objects.
currencies[].currency string A currency code.
currencies[].percentage float The percentage to discount by.

The promotion code object

A promotion code is represented by the following, very simple, object.

{
  "code":"ZXY_CBA"
}
Name Type Description
code string Any string

Create a promotion

Create a new promotion.

curl -X POST https://api.moltin.com/v2/promotions \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type":"promotion",
    "name": "Promo #1",
    "description": "Initial Promotion",
    "enabled": true,
    "promotion_type": "fixed_discount",
    "schema":{
      "currencies":[
        {"currency":"USD", "amount":900},
        {"currency":"GBP", "amount":1100}
      ]
    },
    "start":"2017-01-13",
    "end":"2018-01-13"
  }
}'
Not supported yet

HTTP Request

POST /v2/promotions

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Request Body

Name Type Description
type string "promotion"
name string The name of your promotion.
description string A description of your promotion
enabled boolean true if enabled, false if not.
promotion_type string One of: fixed_discount, percentage_discount
schema object One of: fixed_schema, percent_schema
start string 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.

The promotion_type and schema fields are closely linked. The schema must contain the correct promotion type schema corresponding to the promotion_type value.

Get a list of promotions

Get a list of all promotions

curl -X GET https://api.moltin.com/v2/promotions \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/promotions

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

Get a promotion

Get a single promotion.

curl -X GET https://api.moltin.com/v2/promotions/{PROMOTION_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/promotions/{PROMOTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

Name Type Description
promotion_id uuid Unique promotion identifier

Update a promotion

Update a promotion.

curl -X PUT https://api.moltin.com/v2/promotions/{PROMOTION_ID} \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data": {
    "type":"promotion",
    "id": "PROMOTION_ID",
    "name": "Promo #1",
    "description": "Initial Promotion",
    "enabled": true,
    "promotion_type": "fixed_discount",
    "schema":{
      "currencies":[
        {"currency":"USD", "amount":900},
        {"currency":"GBP", "amount":1100}
      ]
    },
    "start":"2017-11-13",
    "end":"2019-11-13"
  }
}'
Not supported yet

HTTP Request

PUT /v2/promotions/{PROMOTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

Name Type Description
promotion_id uuid Unique promotion identifier

Request Body

Name Type Description
type string "promotion"
id uuid Unique promotion identifier.
name string The name of your promotion.
description string A description of your promotion.
enabled boolean true if enabled, false if not.
promotion_type string One of: fixed_discount, percentage_discount
schema object One of: fixed_schema, percent_schema
start string 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.

Delete a promotion

Delete a promotion.

curl -X DELETE https://api.moltin.com/v2/promotions/{PROMOTION_ID} \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

DELETE /v2/promotions/{PROMOTION_ID}

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

Name Type Description
promotion_id uuid Unique promotion identifier

Create promotion codes

Create a promotion code.

curl -X POST https://api.moltin.com/v2/promotions/{PROMOTION_ID}/codes \
     -H "Authorization: Bearer XXXX" \
     -d $'{
  "data":{
    "type":"promotion_codes",
    "codes": [
      {"code":"ZXY_CBA"},
      ...
      {"code":"ABC_XYZ"}
    ]
  }
}'
Not supported yet

You can create multiple codes for a promotion in one request. Payload for promotion creation is an array of these promotion code objects.

HTTP Request

POST /v2/promotions/{PROMOTION_ID}/codes

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

Name Type Description
promotion_id uuid Unique promotion identifier

Request Body

Name Type Description
type string "promotion_codes"
codes array An array of objects.
codes.code string A string to use as a code for the promotion.

Get a list of codes for a promotion

curl https://api.moltin.com/v2/promotions/{PROMOTION_ID}/codes \
     -H "Authorization: Bearer XXXX"
Not supported yet

HTTP Request

GET /v2/promotions/{PROMOTION_ID}/codes

Headers

Header Type Description
Authorization string The Bearer token to grant access to the API. required

URL Parameters

Name Type Description
promotion_id uuid Unique promotion identifier
Code language options: cURL JavaScript