Navbar
About MoreCommerce
Contact Us

MoreCommerce Merchant API and MoreCommerce Platform Notifications

Getting Started

The MoreCommerce Merchant API and MoreCommerce Platform Notifications suite offers programmatic access to e-commerce entities (inventory and orders) on the MoreCommerce marketplaces and distribution network, to operate on behalf of the merchants.

MoreCommerce Merchant API

The MoreCommerce Merchant API offers seller management of inventory and orders on the MoreCommerce sites and distribution network.

The API can be used by MoreCommerce Partners to manage products and orders on behalf of their sellers. In order to start using the API, a Partner needs to register (as an "application") with MoreCommerce. The Partner will be provided with application API credentials (described in the following sections). The registered Partner will then be able to expose an Authentication & Authorization flow to its sellers, so that sellers can authorize the Partner to manage existing MoreCommerce accounts on their behalf.

This is a HTTP REST API with JSON formatted content, accessible at bisapi.morecommerce.com. All requests should use the HTTPS protocol.

MoreCommerce Platform Notifications

With Platform Notifications, MoreCommerce offers API Partners a mechanism to subscribe to platform events and be notified when these events occur. MoreCommerce Platform Notifications accompany the MoreCommerce Merchant API.

In order to subscribe to platform events, Partners first need to set up a Merchant API integration and subscribe to one or more classes of platform notifications. Notifications are sent for events relevant to the merchants managed by the Partner application.

In v1, order notifications are available, covering order creation and order updates in a single notification call.

Notifications are HTTP POST calls with JSON formatted content, sent to a base URL provided by the Partner and a suffix chosen by MoreCommerce, which will be different for each notification type. The Partner is required to respond with HTTP 200 OK to notification calls. Redelivery is not available in v1.

In v1, notification subscriptions are set up on request and the Partner needs to provide a base URL that they own (e.g. http://example.com/morecommerce-notifications).

Changelog

2021-10

Added

Extended shipping details (ground and expedited shipping profiles) in the product calls.

Added

Shipping service in the order calls.

2020-04

Documentation review. Removed 'pickperfect.com' as a site option in the API.

2019-06

Use 'https://bisapi.morecommerce.com' as the base URL of the API. The 'https://bisapi.opensky.com' will be obsoleted on 08/01/2019.

2018-11

OpenSky Merchant API becomes MoreCommerce Merchant API (with no changes to the API contract or features). Read more about MoreCommerce.

MoreCommerce Merchant API

V1 - 2016-11

Public version of the MoreCommerce Merchant API (products and orders), with support for MoreCommerce sites.

2017-01

Added

Seller specific calls for account setup and update operations.

2017-06

Changed

Maximum allowed SKU size was increased from 30 to 100 characters.

Added

New attribute in product calls, 'doesNotHaveIdentifiers', which indicates whether the product does not have identifiers such as ASIN, MPN and brand, ISBN etc.

2017-08

Added

New field added in all API responses: 'callReferenceId', used to uniquely reference a specific call for debugging purposes.

MoreCommerce product create and update limits: Channel Limits.

MoreCommerce Platform Notifications

V1 - 2016-08

MoreCommerce Platform Notifications for order create and update events.

Authentication and Authorization

Partner Registration

On request, each Partner application is provided with:

Each Partner application should provide:

to be used on the seller authorization flows.

To use the MoreCommerce Platform Notifications, the Partner needs to provide:

Message Integrity

Sample Java snippet for signature calculation

import org.apache.commons.codec.binary.Base64; import org.apache.commons.codec.digest.HmacUtils; secretKeyBytes = secretKey.getBytes("UTF-8"); stringToSignBytes = stringToSign.getBytes("UTF-8"); signature = Base64.encodeBase64URLSafeString(HmacUtils.hmacSha1(secretKeyBytes, stringToSignBytes))

Sample PHP snippet for signature calculation

function urlsafe($data) { return rtrim(strtr($data, '+/', '-_'), '='); } $signature = urlsafe(base64_encode(hash_hmac("sha1", $stringToSign, $secretKey, true)));

Example PHP code to calculate the signature on a Get Order call

<?php function urlsafe($data) { return rtrim(strtr($data, '+/', '-_'), '='); } // relative API call URI $stringToSignComponents[] = "/bis-api/public/api/v1/orders/get"; // request date $stringToSignComponents[] = "2017-05-31T12:49:53.023Z"; // user key id $stringToSignComponents[] = "241b8d1d-a45f-4ff2-a708-ac583c7265a1"; // request body $stringToSignComponents[] = '{"orderId":123456789,"sellerId":12345}'; // application secret key $appSecretKey = "gceYcrrHggzgfwksDWATSjo9eKaTk0W2sI3MtLg4yZGxjsheQGy0xYN0na1n"; $stringToSign = implode("\n", $stringToSignComponents); $signature = urlsafe(base64_encode(hash_hmac("sha1", $stringToSign, $appSecretKey, true))); print("\nSignature: $signature\n\n"); ?>

Example PHP code to calculate the signature on a List Categories call

<?php function urlsafe($data) { return rtrim(strtr($data, '+/', '-_'), '='); } // relative API call URI $stringToSignComponents[] = "/bis-api/public/api/v1/categories/list"; // request date $stringToSignComponents[] = "2017-05-31T12:49:53.023Z"; // request body $stringToSignComponents[] = '{"channel":"OPENSKY","page":1,"pageSize":100}'; // application secret key $appSecretKey = "gceYcrrHggzgfwksDWATSjo9eKaTk0W2sI3MtLg4yZGxjsheQGy0xYN0na1n"; $stringToSign = implode("\n", $stringToSignComponents); $signature = urlsafe(base64_encode(hash_hmac("sha1", $stringToSign, $appSecretKey, true))); print("\nSignature: $signature\n\n"); ?>

Example C# code to calculate the signature on a List Categories call

using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Security.Cryptography; using System.Web; namespace Rextester { public class Program { public static void Main(string[] args) { string relativeAPICallURI = "/bis-api/public/api/v1/categories/list"; string requestDate = "2017-06-20T10:05:00.000Z"; string requestBody = "{\"channel\":\"OPENSKY\",\"page\":1,\"pageSize\":100}"; string[] stringToSignComponents = new string[3] {relativeAPICallURI, requestDate, requestBody}; string stringToSign = String.Join("\n", stringToSignComponents); string secretKey = "replace_with_the_application_secret_key"; Encoding encoding = new UTF8Encoding(); var keyByte = encoding.GetBytes(secretKey); using (HMACSHA1 hmacSha1 = new HMACSHA1(keyByte)) { byte[] stringToSignBytes = encoding.GetBytes(stringToSign); byte[] hashmessage = hmacSha1.ComputeHash(stringToSignBytes); string base64Encoded = HttpServerUtility.UrlTokenEncode(hashmessage); if (!string.IsNullOrEmpty(base64Encoded)) { if (Char.IsNumber(base64Encoded[base64Encoded.Length - 1])) { base64Encoded = base64Encoded.Substring(0, base64Encoded.Length - 1); } } Console.WriteLine("Signature: " + base64Encoded); } } } }

All API calls and requests must be signed. The formula to calculate the signature is:

where the

and the

API Call Authorization

Sample API call

curl -X POST \ https://bisapi.morecommerce.com/bis-api/public/api/v1/orders/search \ -H 'content-type: application/json' \ -H 'X-OPENSKY-PUBLIC-API-APP-KEY-ID: 98333a23-e6cf-4acd-9502-d7b94302ba41' \ -H 'X-OPENSKY-PUBLIC-API-REQ-DATE: 2017-04-24T14:23:04.684Z' \ -H 'X-OPENSKY-PUBLIC-API-REQ-SIGN: AIB1k0YMc1y2uCRAsEb173T011' \ -H 'X-OPENSKY-PUBLIC-API-USER-KEY-ID: 32f31300-9b80-4d2d-b806-fba51736a761' \ -d '{ "sellerId":12345, "page":1, "pageSize":100, "filters":[ { "field":"CHANNEL", "operator":"EQUAL", "value":"OPENSKY" }, { "field":"STATUS", "operator":"EQUAL", "value":"pending" } ] }'

The following HTTP headers need to be provided with each API call:

Header Key Description
X-OPENSKY-PUBLIC-API-APP-KEY-ID API application key id (provided on Partner registration) .
X-OPENSKY-PUBLIC-API-USER-KEY-ID User API Key id (provided in the A&A Seller Flow).
X-OPENSKY-PUBLIC-API-REQ-DATE Date and time of the request (ISO 8601 format).
X-OPENSKY-PUBLIC-API-REQ-SIGN Request signature.

The API verifies that the request date is a past timestamp, at most 5 minutes older than the current time on the server.

The request signature is calculated with the previously described formula using the Partner's secret key and the string to sign, composed of:

where:

All API calls used for retrieving or modifying sellers, products, orders or taxonomy are POST requests, with authentication information sent as the HTTP headers described above and the call data as POST request body. An example request is on the right.

A&A Seller Flow

This section applies to Partners that manage multiple merchants and MoreCommerce stores. In order to manage inventory on MoreCommerce sites on a merchant's behalf, the Partner application needs to take its merchants through an A&A flow, comprised of the following steps:

If the seller authorized the Partner - MoreCommerce relationship, the Partner will need to save the parameters provided on the Success Return URL, in order to use them in subsequent API calls.

Entry Point

The request signature is calculated with the previously described formula using the Partner's secret key and the string to sign, the latter composed of:

where reqDate and data are the values of the parameters above, and reqURI is /bis-api/public/auth/seller/init.

Success Return URL

The response signature is calculated with the previously described formula using the Partner's secret key and:

The userKeyId provided on the success return URL is the seller specific token, and will be needed in subsequent API calls.

The user key is valid for 18 months, with the exact dates indicated by userKeyValidFrom and userKeyValidUntil. A new key must be generated before the expiration date, to ensure uninterrupted service.

Failure Return URL

The following error codes can be expected:

Code Error Description
1 Invalid request Some of the request parameters are invalid.
2 Unauthorized The request is not properly signed or the partner application is not recognized.
3 Request expired The merchant did not complete the flow in the permitted time period (3 hours).
4 Canceled by user The merchant cancelled authorizing the application for the Merchant API.
99 Internal error Internal error.

Call Summary

Products

MoreCommerce Merchant API calls for product operations.

Method Description
POST /bis-api/public/api/v1/products/create Bulk create products.
POST /bis-api/public/api/v1/products/get Retrieve a single product.
POST /bis-api/public/api/v1/products/list Retrieve a list of products.
POST /bis-api/public/api/v1/products/search Search and filter for products.
POST /bis-api/public/api/v1/products/update Bulk update existing products.

Taxonomy

MoreCommerce Merchant API calls for taxonomy listing.

Method Description
POST /bis-api/public/api/v1/categories/list Retrieve the MoreCommerce product category list.

Orders

MoreCommerce Merchant API calls for order operations.

Method Description
POST /bis-api/public/api/v1/orders/get Retrieve a single order.
POST /bis-api/public/api/v1/orders/list Retrieve a list of orders.
POST /bis-api/public/api/v1/orders/search Search and filter for orders.
POST /bis-api/public/api/v1/orders/ship Ship orders.

Recommendations

The request format for each of the API calls is detailed in the sections below. The request body should be a valid JSON. Content-Type should be set to application/json. Only the documented fields should be provided in the JSON request content. Extra fields in the requests might cause the calls to fail.

The API verifies that the request date for each call is a past time, at most 5 minutes older than the current time on the API server. We recommend synchronizing the clock on the machines issuing the calls with an NTP server.

The API contract is subject to changes within the same version as long as they are non breaking (e.g. new fields can be added to the API call responses, but existing fields cannot be removed).

API Response Codes

The API calls will return an HTTP response with one of the following HTTP codes, and, in some cases, a JSON formatted body.

HTTP Code Description
200 OK The request was successful, see the response body for the outcome of the requested operation.
400 Bad Request The server will not process the request due to an apparent client error.
401 Unauthorized Authentication failure, the caller does not have the necessary credentials.
429 Too Many Requests The user has sent too many requests in a given interval.
500 Internal Server Error There was an unexpected error in the application.

If the HTTP call was successful, but the requested operation resulted in one or more errors or issued warnings, the error field contained in the response will be an array of Error objects. The Error object is also available for error HTTP codes.

The Error object has the following properties:

Parameter Type Description
code integer Error code (possible values below).
message string User friendly error message.
severity string Error class. Can be ERROR or WARNING.
techDetails string Additional details about the error, suitable for being parsed by the calling application.
type string Error type. Can be REQUEST or SYSTEM, indicating whether the error was identified on the part of the caller or of the API.

A bulk operation can be partially successful. (For example, the Create Products call with a bulk request of 10 products could result in 5 successfully created products, 3 errors and 2 products created with warnings.). The error codes refer to the individual entities in the bulk request, and can be the following:

Code Severity Description
400 ERROR Validation errors (missing or invalid values etc.).
404 ERROR Entity not found (e.g. trying to update a product that does not exist).
500 ERROR Internal server error.
1000 ERROR Unsupported operation.
2000 ERROR Operation could not be completed on channel.
3000 ERROR Reached allotted quota (see Channel Limits).
5000 WARNING Operation had side effects.
6000 WARNING Value was altered or a default was set.
7000 WARNING Value was ignored (invalid or not applicable).

Additional details for the codes above are provided in the error message and/or the technical details.

API Rate Limits

Monthly Call Limit

Each partner application is limited to a maximum of 150,000 calls per calendar month. All types of calls for which authorization was successful count towards the limit. All additional calls will be dropped.

Burst Limit

The maximum burst rate should not exceed 150 calls per 15 minutes. For any given 15 minute interval, the API guarantees that 150 calls will not be rate limited. Any additional calls are likely to be dropped. This applies to each Partner application, and to all types of calls for which authorization was successful.

Call Responses

Response body for over the limit calls:

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "errors":[ { "severity":"ERROR", "type":"REQUEST", "code":429, "message":"Too Many Requests.", "techDetails":null } ] }

Calls that are dropped due to exceeded limits will return HTTP status 429 (Too Many Requests) - see content body on the right.

All API calls also provide the following header fields in the response, irrespective of the rate limits being reached or not. They reflect the real-time API usage.

Header Key Description
X-RateLimit-BurstLimit Burst limit counter (number of calls allowed per 15 minutes).
X-RateLimit-BurstRemaining Number of calls allowed before reaching the burst limit.
X-RateLimit-MonthLimit Monthly limit counter.
X-RateLimit-MonthRemaining Number of calls allowed before reaching the monthly limit.

Channel Limits

Response body for channel quota reached:

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "errors":[ { "severity":"ERROR", "type":"REQUEST", "code":3000, "message":"Daily product updates quota reached", "techDetails":null } ] }

The limits for product operations for each MoreCommerce merchant are the following :

Upon reaching the quota, the API will return ERROR code 3000, example on the right. In these cases, the product creates or updates will not go through.

Product Calls

Use product calls to manage inventory by creating products, updating quantities or other product parameters and retrieving existing product data.

Create Products

Create Products - example request body:

{ "sellerId":12345, "products":[ { "SKU":"PROD-2016-01", "name":"Sample Product One", "description":"Sample product description.", "price":10.25, "MSRP":15, "quantity":100, "condition":"NEW", "brand":"My Sample Brand", "identifiers":{ "UPC":"123456789012", "MPN":"testmpn" }, "dimensions":{ "weight":0.88 }, "attributes":[ { "name":"color", "value":"white" }, { "name":"cut", "value":"high waist" } ], "productVideoURL":"https://www.youtube.com/watch?v=somevideo", "images":[ { "order":0, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" }, { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" } ], "channels":{ "opensky":{ "status":"PUBLISHED", "category":"Sporting Goods/Cycling/Bicycles", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":1, "customizable":false, "customizationPrompt":null, "shippingDetails":{ "price":1.75, "priceWithAdditional":1.25, "estimatedDays":7 }, "SEOKeywords":"Sample Product One, My Sample Brand, Bicycle, purchase, buy, sale, MoreCommerce, shopping", "SEODescription":"Purchase Sample Product One from my store on MoreCommerce." } }, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":1, "priceWithAdditional":1, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null } ], "estimatedDays":null, "details":null } } ] }

Bulk create products.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
product array Array of Product JSON objects. required

The product array in the request should contain minimum 1 product and maximum 100 products.

The Product object has the following structure:

Name Type Description
SKU string Stock keeping unit.
Maximum 100 characters. SKUs are unique per merchant.
name string Product title as it should appear on the channel.
Maximum 140 characters.
Product titles are unique per merchant on the MoreCommerce channels.
description string Product description.
Maximum 1MB.
price number Selling price
(number > 0, two decimals).
landedCost number Specify landed cost instead of item price.
This field is currently unused, and requires special permissions.
MSRP number Manufacturer's suggested retail price
(number > 0, two decimals).
quantity integer Quantity available for sale.
Use 0 for out of stock items, and null for unlimited/untracked inventory quantity.
condition string Item condition, default NEW.
brand string Product's brand.
Maximum 255 characters.
doesNotHaveIdentifiers boolean Set to 'true' if the product does not have product identifiers (MPN and brand, ASIN etc.). Can be null.
identifiers object One or more of the identifiers below.
identifiers.MPN string Maximum 100 characters.
identifiers.ASIN string 10 characters, digits and/or letters.
identifiers.EAN string 8, 13 or 14 digits.
identifiers.GTIN string 8, 12, 13 or 14 digits.
identifiers.ISBN string 10 or 13 digits (last character may be "X" if length is 10).
identifiers.JAN string 8 or 13 digits.
identifiers.UPC string 12 digits.
dimensions object Numeric values only (do not include units).
The units of measurement are inches for size and pounds for weight.
dimensions.height number Height of the product in inches.
dimensions.length number Length of the product in inches.
dimensions.width number Width of the product in inches.
dimensions.weight number Weight of the product in pounds.
attributes array Standard product attributes (not to be confused with variation attributes).
Whenever available, we recommend providing the following attributes: ageGroup, color, gender, material, pattern, size.
productVideoURL string The URL link to a YouTube video of the product, if available. Enter the complete YouTube URL.
images array Array of Image JSON objects.
channels.opensky object Specific properties for listing the product on the sites of the OpenSky (MoreCommerce) channel. See the Opensky Channel object description.
variations object If the product has multiple variations, specify here the options, values and variants (option-value combinations).
See the Variations object description.
shippingDetails object Support for shipping profiles. See the Shipping Details object description.

The following properties of the product are read-only. They are not used and should not be sent in the Create call, but are returned in the Get, List and Search calls:

Name Type Description
productId integer MoreCommerce internal product id.
createdAt string Product create date, ISO 8601 format.
updatedAt string Product last update date, ISO 8601 format.
deletedAt string Product delete date, ISO 8601 format.


The Images object has the following structure:

At least one image is required. Maximum 12 images are allowed.

Name Type Description
order integer
imageURL string The merchant's full product image URLs (e.g. http://www.morecommerce.com/fake_image.jpg).


The MoreCommerce Channel object has the following structure:

Name Type Description
sites object MoreCommerce sites to publish on. By default, all products are published on morecommerce.com.
status string Accepted values for create/update calls: DRAFT or PUBLISHED. (The DRAFT status can be used to hide products, delete operations are not supported.)
Possible values for get/search/list: DRAFT, PUBLISHED or FAILED.
category string Should be a valid MoreCommerce category path.
Use the List Categories call to get the full list of categories.
customizable boolean Use true to indicate it's a customizable product.
customizationPrompt string Customization prompt to be displayed to the buyer.
exclusive boolean The product is sold exclusively on MoreCommerce.
maxDiscountPercentageLocked boolean See this help article for discounts.
maxProductDiscount integer See this help article for discounts.
shippingDetails object
shippingDetails.price number Shipping price for Continental United States.
shippingDetails.priceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Continental United States.
shippingDetails.alaskaHawaiiPrice number Shipping price for Alaska & Hawaii.
shippingDetails.alaskaHawaiiPriceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Alaska & Hawaii.
shippingDetails.puertoRicoPrice number Shipping price for Puerto Rico.
shippingDetails.puertoRicoPriceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Puerto Rico.
shippingDetails.details string
shippingDetails.estimatedDays integer
storefrontPlacement integer Ranking for the item placement within the merchant store page.


Snippet from the Create Product call, with a shipping details JSON example:

{... "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":1, "priceWithAdditional":0.5, "alaskaHawaiiPrice":2.00, "alaskaHawaiiPriceWithAdditional":1.00, "puertoRicoPrice":3.00, "puertoRicoPriceWithAdditional":3.50 }, { "service":"EXPEDITED_1_DAY", "price":3.00, "priceWithAdditional":2.00 } ] } ...}


The Shipping Details object has the following structure:

If you're included in the shipping expansion program, this object has to be used instead of channels.opensky.shippingDetails to define ground and expedited shipping profiles. If this object is provided, channels.opensky.shippingDetails are ignored. Contact MoreCommerce to be included in the program.

Name Type Description
profiles array Array of shipping profile objects for ground or expedited shipping services, with the properties described below.
profiles[].service string Accepted values: STANDARD_GROUND, ECONOMY_GROUND, EXPEDITED_1_DAY, EXPEDITED_2_DAY. Only one ground service (either STANDARD_GROUND or ECONOMY_GROUND) is required, and none or any of the expedited services can be specified.
profiles[].price number Shipping price for Continental United States. This is required for product creates, for the ground profile.
profiles[].priceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Continental United States.
profiles[].alaskaHawaiiPrice number Shipping price for Alaska & Hawaii.
Applies only to ground shipping profiles.
profiles[].alaskaHawaiiPriceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Alaska & Hawaii.
Applies only to ground shipping profiles.
profiles[].puertoRicoPrice number Shipping price for Puerto Rico.
Applies only to ground shipping profiles.
profiles[].puertoRicoPriceWithAdditional number If an order contains multiple items from a merchant, this is the shipping price for each item after the first.
Applies to Puerto Rico.
Applies only to ground shipping profiles.
estimatedDays integer Number of days (between 1 and 10) it takes to get the product in the mail. Applies only to customizable products, and is ignored for all other products. Regardless of this shipping estimate, custom products must be delivered within 15 business days.
details string


Snippet from the Create Product call, with a variations JSON example:

{... "variations":{ "options":[ { "name":"color", "values":[ "red", "green" ] }, { "name":"size", "values":[ "XXL" ] } ], "variants":[ { "SKU":"SKU_red_XXL", "MSRP":59.99, "attributes":null, "choices":[ { "name":"color", "value":"red" }, { "name":"size", "value":"XXL" } ], "dimensions":{ "width":1, "height":1, "length":1, "weight":0.8 }, "identifiers":null, "images":null, "price":59.99, "quantity":2 }, { "SKU":"SKU_green_XXL", "MSRP":49.99, "attributes":null, "choices":[ { "name":"color", "value":"green" }, { "name":"size", "value":"XXL" } ], "dimensions":{ "width":1, "height":1, "length":1, "weight":0.8 }, "identifiers":null, "images":null, "price":49.99, "quantity":10 } ] } ...}

The Variations object has the following structure:

Name Type Description
options array Array of variation options.
options[].name string Option name.
options[].values array[string] Array of option values (minimum 1).
variants array Array of variant objects with the properties described below.
variants.productId integer Internal id of the variant, not used in the Create Products call.
variants.SKU string Variant SKU.
variants.price number Variant price.
variants.landedCost number Specify landed cost instead of item price.
This field is currently unused, and requires special permissions.
variants.MSRP number Variant MSRP.
variants.quantity integer Variant quantity.
variants.attributes array Variant attribues.
Use this to specify additional product details, which are not variation options.
variants.choices array Array of variation choices.
variants.choices.name string Option name.
variants.choices.value string Option value.
variants.dimensions object Same properties as described in the Product object.
variants.identifiers object Same properties as described in the Product object.
variants.images array See the Image object.

If different "options" (e.g. color, size) can be selected on the product, they should be specified in this object. An option can have multiple "values" (e.g. reg, green, blue for option color). A "variant" is a purchasable product defined by a combination of "choices" for all the defined options (e.g. color: red, size: XXL). Various parameters can be specified per variation, as described below (price, quantity etc.).

Item condition default value is NEW.
In some cases, but not always or guaranteed, products with different conditions can be approved for sale: USED, REFURBISHED, ACCEPTABLE, GOOD, LIKE_NEW, VERY_GOOD, NEW_WITH_BOX_TAGS, NEW_WITHOUT_BOX_TAGS, PREOWNED, VINTAGE and SECOND.

The following fields are required to create a new product:

For one merchant, SKUs and titles should be unique for each product. Providing the same SKU or title for different products can result in duplicate product errors or unexpected behavior.

Response

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "results":[ { "index":0, "productId":10863780, "status":"SUCCESS", "errors":null, "SKU":"PROD-2016-01" } ] }
Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
results array Array of Product Result JSON objects.

The Product Result object has the following structure:

Name Type Description
index integer Index of the product in the request array. Starts from 0.
productId integer The assigned internal product id. Subsequent Get, List or Update product calls will require this id.
SKU string Product SKU, as provided in the request. This should be unique for each merchant.
status string Status of the create operation. Possible values: SUCCESS, FAILED.
errors array Array of Error objects.

Get Product

Example request body:

{ "sellerId":12345, "productId":10402607 }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "product":{ "price":12.55, "quantity":300, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "doesNotHaveidentifiers":true, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" }, { "order":2, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" }, { "order":3, "imageURL":"https://www.somedomain.com/some/path/to/image-3.jpg" }, { "order":4, "imageURL":"https://www.somedomain.com/some/path/to/image-4.jpg" }, { "order":5, "imageURL":"https://www.somedomain.com/some/path/to/image-5.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":1 }, "attributes":null, "channels":{ "opensky":{ "category":"accessories/baby-toddler-accessories/baby-toddler-bags", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":7, "customizable":false, "customizationPrompt":null, "shippingDetails":{ "price":1, "priceWithAdditional":1, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null, "estimatedDays":7, "details":null }, "SEOKeywords":"Sample Product Two, My Sample Brand, toddler bags, purchase, buy, sale, MoreCommerce, shopping", "SEODescription":"Purchase Sample Product Two from my store on MoreCommerce.", "status":"PUBLISHED", "errors":null, "warnings":null, "productURL":null } }, "productId":10402607, "createdAt":"2016-02-23T18:33:39.000+0000", "updatedAt":"2016-03-15T12:15:35.000+0000", "deletedAt":null, "name":"Sample Product Two", "description":"Sample product description.", "condition":null, "brand":null, "variations":{ "options":[ { "name":"size", "values":[ "L", "M" ] } ], "variants":[ { "productId":10402608, "price":22, "quantity":100, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":1 }, "attributes":null, "channels":null, "choices":[ { "name":"size", "value":"L" } ], "SKU":"PROD-2016-02-L", "MSRP":11 }, { "productId":10402609, "price":21, "quantity":200, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":1 }, "attributes":null, "channels":null, "choices":[ { "name":"size", "value":"M" } ], "SKU":"PROD-2016-02-M", "MSRP":12 } ] }, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":1, "priceWithAdditional":1, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null } ], "estimatedDays":null, "details":null }, "SKU":"64ffb62a3e2b826a325449073156d2c9", "MSRP":null, "productVideoURL":null } }

Request

Retrieve a single product by MoreCommerce internal product id.

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
productId integer MoreCommerce internal product id (provided in the Create Products call). required

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
product object Product object.

List Products

Example request body:

{ "sellerId":12345, "productIds": [10685113,10402608,10435480] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "products":[ { "price":13, "quantity":10, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":1 }, "attributes":null, "channels":{ "opensky":{ "category":"accessories/baby-toddler-accessories/other-baby-toddler-accessories", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":2, "customizable":true, "customizationPrompt":"Enter a gift wrap choice (gift box or gift bag):", "shippingDetails":{ "price":1, "priceWithAdditional":1, "alaskaHawaiiPrice":1, "alaskaHawaiiPriceWithAdditional":1, "puertoRicoPrice":1, "puertoRicoPriceWithAdditional":1, "estimatedDays":7, "details":null }, "SEOKeywords":"Sample Product Two, My Sample Brand, toddler bags, purchase, buy, sale, MoreCommerce, shopping", "SEODescription":"Purchase Sample Product Two from my store on MoreCommerce.", "status":"DRAFT", "errors":null, "warnings":null, "productURL":null } }, "productId":10402608, "createdAt":"2016-02-23T18:49:55.000+0000", "updatedAt":"2016-03-10T18:14:53.000+0000", "deletedAt":null, "name":"Sample Product Three", "description":"Sample product description.", "condition":null, "brand":"My Sample Brand", "variations":null, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":1, "priceWithAdditional":1, "alaskaHawaiiPrice":1, "alaskaHawaiiPriceWithAdditional":1, "puertoRicoPrice":1, "puertoRicoPriceWithAdditional":1 } ], "estimatedDays":7, "details":null }, "SKU":"PROD-2016-03", "MSRP":14, "productVideoURL":null }, { "price":null, "quantity":3, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" }, { "order":2, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" }, { "order":3, "imageURL":"https://www.somedomain.com/some/path/to/image-3.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":{ "opensky":{ "category":"Other", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":null, "customizable":false, "customizationPrompt":null, "shippingDetails":{ "price":null, "priceWithAdditional":null, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null, "estimatedDays":null, "details":null }, "SEOKeywords":null, "SEODescription":null, "status":"DRAFT", "errors":null, "warnings":[ "shippingPrice: This value should be a valid number.", "secondaryShippingPrice: This value should be a valid number.", "Weight cannot be blank.", "Please choose a category.", "Please provide a SKU.", "Please enter the price." ], "productURL":null } }, "productId":10435480, "createdAt":"2016-03-01T14:59:04.000+0000", "updatedAt":"2016-03-15T12:15:35.000+0000", "deletedAt":null, "name":"Sample Product Four", "description":"Sample product description.", "condition":"NEW", "brand":null, "variations":{ "options":[ { "name":"color", "values":[ "black", "blue" ] }, { "name":"size", "values":[ "l", "m" ] } ], "variants":[ { "productId":10435481, "price":1, "quantity":1, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":null, "choices":[ { "name":"color", "value":"blue" }, { "name":"size", "value":"l" } ], "SKU":"PROD-2016-04-l", "MSRP":null }, { "productId":10435482, "price":2, "quantity":2, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":null, "choices":[ { "name":"color", "value":"black" }, { "name":"size", "value":"m" } ], "SKU":"PROD-2016-04-m", "MSRP":null } ] }, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":null, "priceWithAdditional":null, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null } ], "estimatedDays":null, "details":null }, "SKU":"PROD-2016-04", "MSRP":null, "productVideoURL":null }, { "price":1, "quantity":100, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":0, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":2, "height":1, "length":null, "weight":1 }, "attributes":null, "channels":{ "opensky":{ "category":"accessories/other-accessories", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":1, "customizable":false, "customizationPrompt":null, "shippingDetails":{ "price":0.15, "priceWithAdditional":0.1, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null, "estimatedDays":7, "details":null }, "SEOKeywords":null, "SEODescription":null, "status":null, "errors":null, "warnings":null, "productURL":null } }, "productId":10685113, "createdAt":"2016-04-26T14:08:36.000+0000", "updatedAt":"2016-04-26T14:08:36.000+0000", "deletedAt":null, "name":"Sample Product Five", "description":"Sample product description.", "condition":null, "brand":null, "variations":null, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":0.15, "priceWithAdditional":0.1, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null } ], "estimatedDays":7, "details":null }, "SKU":"PROD-2016-05", "MSRP":1, "productVideoURL":null } ] }

Request

Retrieve multiple products by MoreCommerce internal product ids.

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
productIds array Array of MoreCommerce internal product ids (provided in the Create Products call). required

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
products array Array of Product objects.

Search Products

Example request body:

{ "sellerId":12345, "page":1, "pageSize":100, "filters":[ { "field":"NAME", "operator":"EQUAL", "value":"Sample Product Six" } ] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "products":[ { "price":null, "quantity":3, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" }, { "order":2, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" }, { "order":3, "imageURL":"https://www.somedomain.com/some/path/to/image-3.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":{ "opensky":{ "category":"Other", "maxProductDiscount":null, "maxDiscountPercentageLocked":false, "exclusive":false, "storefrontPlacement":null, "customizable":false, "customizationPrompt":null, "shippingDetails":{ "price":null, "priceWithAdditional":null, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null, "estimatedDays":null, "details":null }, "SEOKeywords":null, "SEODescription":null, "status":"DRAFT", "errors":null, "warnings":[ "shippingPrice: This value should be a valid number.", "secondaryShippingPrice: This value should be a valid number.", "Weight cannot be blank.", "Please choose a category.", "Please provide a SKU.", "Please enter the price." ], "productURL":null } }, "productId":10435480, "createdAt":"2016-03-01T14:59:04.000+0000", "updatedAt":"2016-03-15T12:15:35.000+0000", "deletedAt":null, "name":"Sample Product Six", "description":"Sample product description.", "condition":"NEW", "brand":null, "variations":{ "options":[ { "name":"color", "values":[ "black", "blue" ] }, { "name":"size", "values":[ "l", "m" ] } ], "variants":[ { "productId":10435481, "price":1, "quantity":1, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-1.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":null, "choices":[ { "name":"color", "value":"blue" }, { "name":"size", "value":"l" } ], "SKU":"PROD-2016-06-bl", "MSRP":null }, { "productId":10435482, "price":2, "quantity":2, "identifiers":{ "EAN":null, "GTIN":null, "UPC":null, "JAN":null, "ISBN":null, "ASIN":null, "MPN":null }, "images":[ { "order":1, "imageURL":"https://www.somedomain.com/some/path/to/image-2.jpg" } ], "dimensions":{ "width":null, "height":null, "length":null, "weight":null }, "attributes":null, "channels":null, "choices":[ { "name":"color", "value":"black" }, { "name":"size", "value":"m" } ], "SKU":"PROD-2016-01-bk", "MSRP":null } ] }, "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "price":null, "priceWithAdditional":null, "alaskaHawaiiPrice":null, "alaskaHawaiiPriceWithAdditional":null, "puertoRicoPrice":null, "puertoRicoPriceWithAdditional":null } ], "estimatedDays":null, "details":null }, "SKU":"PROD-2016-06", "MSRP":null, "productVideoURL":null } ], "totalCount":1 }

Request

Retrieve a list of products, optionally filtered by a condition.

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
page Page number (default 1). integer required
filters array Array of objects with filtering criteria (see below).
All conditions in the filter array have to match, filters are combined with the "AND" operator.
optional
filters.field string Supported search fields: NAME, OPENSKY_STATUS
filters.operator string Supported operators: EQUAL, IS_NULL
filters.value string Supported values for OPENSKY_STATUS: DRAFT, PUBLISHED, FAILED

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
products array Array of Product objects.
totalCount integer Total count of products that match the search.
pageSize integer Page size (default 100, max 100)

Update Products

Example request body:

{ "sellerId":12345, "products":[ { "productId":10863780, "description":"Sample product description - updated.", "price":10, "quantity":99 } ] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "results":[ { "index":0, "productId":10863780, "status":"SUCCESS", "errors":null, "SKU":"PROD-2016-01" } ] }

Bulk update products. Partial updates are permitted, product id is required.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
products array Product JSON objects. required

Partial updates are supported in the API - see example on the right.

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
results array Array of Product Result JSON objects.

Taxonomy Calls

List Categories

Example request body:

{ "channel":"OPENSKY", "page":1, "pageSize":10 }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "categories":[ "accessories/baby-toddler-accessories/baby-belts", "accessories/baby-toddler-accessories/baby-toddler-bags", "accessories/baby-toddler-accessories/baby-toddler-gloves-mittens", "accessories/baby-toddler-accessories/baby-toddler-hair-accessories", "accessories/baby-toddler-accessories/baby-toddler-hats", "accessories/baby-toddler-accessories/baby-toddler-leggings-tights", "accessories/baby-toddler-accessories/baby-toddler-scarves", "accessories/baby-toddler-accessories/baby-toddler-sunglasses", "accessories/baby-toddler-accessories/baby-toddler-ties", "accessories/baby-toddler-accessories/other-baby-toddler-accessories" ], "totalCount":1934 }

Get a full list of MoreCommerce categories.

Authorization

This API call is not user specific and does not require a user:

Request

Name Type Description Notes
channel string MoreCommerce site for which the taxonomy is retrieved.
Use OPENSKY for all supported MoreCommerce sites.
required
page integer Page number (default 1). required
pageSize integer Number of records per page (default 100, max 100). required

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
categories array Array of category path strings, corresponding to the requested page.
totalCount integer Total category count in the requested taxonomy.

Order Calls

Use order calls to search for orders, retrieve order data and send shipping information to MoreCommerce.

Get Order

Example request body:

{ "sellerId":12345, "orderId":622415 }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "order":{ "orderId":622415, "channel":"OPENSKY", "channelOrderId":"903377644", "channelSellerId":"55965b3b4b3d6fe0218b657d", "channelBuyerId":"55c3719e4b3d6f6e288b5c19", "site":"OPENSKY", "status":"canceled", "createdAt":"2016-08-03T09:19:26.000+0000", "shippingPrice":1, "handlingPrice":0, "tax":0, "giftWrapPrice":0, "discount":null, "subtotal":1, "total":2, "items":[ { "orderItemId":704485, "channelOrderItemId":"3798765", "productId":12344819, "channelProductId":"579f0bd5e22461022524b4b7", "name":"Sample Product Seven", "status":"canceled", "quantity":1, "quantityShipped":0, "price":1, "shippingPrice":1, "handlingPrice":null, "tax":0, "taxRate":0, "taxShipping":false, "giftWrapPrice":null, "discount":0, "undiscountedPrice":1, "shippingPaid":null, "taxPaid":null, "weight":1, "giftWrap":false, "giftMessage":null, "customizable":false, "customizationPrompt":null, "customization":null, "returnDays":0, "shippingEstimatedDays":7, "SKU":"PROD-2016-07" } ], "packages":[ { "orderPackageId":558873, "channelOrderPackageId":"2957773", "carrier":"usps", "trackingNumber":"7Fe2EmCwh3YQMrpK7Zla", "weight":null, "shippedAt":"2016-08-16T05:30:39.000+0000", "packageItems":[ { "orderItemId":704485, "quantity":1 } ] } ], "shippingService":"ECONOMY_GROUND", "shippingAddress":{ "fullName":"Jane MoreCommerce", "address1":"152 W. 25th St.", "address2":"12th Floor", "city":"New York", "county":null, "state":"NY", "zip":"10001", "countryCode":"USA", "phoneNumber":null, "phoneExt":null } } }

Retrieve a single order by MoreCommerce internal order id.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
orderId integer MoreCommerce internal order id (provided in the Search Orders API call). required

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
order object Order object, see below.

The Order object has the following structure:

Name Type Description
orderId integer MoreCommerce internal order id (used as identifier in all API calls).
channel string Sales channel on which the order was created. Only one channel supported at the moment (OPENSKY).
channelOrderId string Channel specific seller order id. For MoreCommerce, this is the id shown in the morecommerce.com Merchant Toolkit.
channelSellerId string Channel specific seller id.
channelBuyerId string Channel specific buyer id.
site string MoreCommerce site on which the order was created. Possible values: OPENSKY, DOTANDBO, MORECOMMERCE etc.
status string MoreCommerce order status. Possible values (at 06/20/2017): review, in_holding, pending, processing, complete, canceled
(more information on order states here).
createdAt string Order creation date (ISO 8601 date format).
shippingPrice number Total shipping price.
handlingPrice number Total handling price.
tax number Total tax.
giftWrapPrice number Total gift wrapping cost.
discount number Total discount (field currently unused).
subtotal number Order subtotal (total items cost).
total number Order total.
items array Array of Order Item objects.
packages array Array of Order Package objects.
shippingService string MoreCommerce shipping service. Possible values: STANDARD_GROUND, ECONOMY_GROUND, EXPEDITED_1_DAY, EXPEDITED_2_DAY. Can be null.
shippingAddress object Order shipping address.
shippingAddress.fullName string
shippingAddress.address1 string
shippingAddress.address2 string
shippingAddress.city string
shippingAddress.county string
shippingAddress.state string
shippingAddress.zip string
shippingAddress.countryCode string
shippingAddress.phoneNumber string
shippingAddress.phoneExt string

The Order Item object has the following structure:

Name Type Description
orderItemId integer MoreCommerce internal order item id.
productId integer MoreCommerce internal product id (used in Product Calls).
If the product is a variation, this is the variation id.
parentProductId integer MoreCommerce internal product id for a variation parent (if applicable).
channelProductId string Channel specific product id.
name string Item title.
status string Status of the order item.
Possible values (at 08/16/2016): pending, processing, warehouse, shipped, canceled, returned.
quantity integer Item's quantity sold.
quantityShipped integer Item's quantity shipped.
price number Item's price. If it is a multi-unit item, this is the total price.
shippingPrice number Item's shipping price.
handlingPrice number Item's handling price.
tax number Item's tax.
taxRate number Item's tax rate.
taxShipping boolean Item's shipping tax.
giftWrapPrice number Item's gift wrapping cost.
discount number Item's discount.
undiscountedPrice number Item price, before discount.
shippingPaid number Shipping amount paid.
taxPaid number Tax amount paid.
weight number Item's weight.
giftWrap boolean If the the item should be gift wrapped.
giftMessage string Message for gift item.
customizable boolean If the item is customizable.
customizationPrompt string Customization prompt.
customization string Customization message.
returnDays integer Number of days for returns.
shippingEstimatedDays integer Shipping estimate.
SKU string Item's SKU.

The Order Package object has the following structure:

Name Type Description
orderPackageId integer MoreCommerce internal package id.
channelOrderPackageId integer Channel specific package id.
carrier string Shipping carrier.
trackingNumber string Tracking number.
weight number Package weight (currently unused).
shippedAt string Shipping date (ISO 8601 date format).
packageItems array Array of package item objects.
packageItems.orderItemId integer
packageItems.quantity integer

List Orders

Example request body:

{ "sellerId":12345, "orderIds":[622415,622475] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "orders":[ { "orderId":622415, "channel":"OPENSKY", "channelOrderId":"903377644", "channelSellerId":"55965b3b4b3d6fe0218b657d", "channelBuyerId":"55c3719e4b3d6f6e288b5c19", "site":"OPENSKY", "status":"canceled", "createdAt":"2016-08-03T09:19:26.000+0000", "shippingPrice":1, "handlingPrice":0, "tax":0, "giftWrapPrice":0, "discount":null, "subtotal":1, "total":2, "items":[ { "orderItemId":704485, "channelOrderItemId":"3798765", "productId":12344819, "channelProductId":"579f0bd5e22461022524b4b7", "name":"Sample Product Seven", "status":"canceled", "quantity":1, "quantityShipped":0, "price":1, "shippingPrice":1, "handlingPrice":null, "tax":0, "taxRate":0, "taxShipping":false, "giftWrapPrice":null, "discount":0, "undiscountedPrice":1, "shippingPaid":null, "taxPaid":null, "weight":1, "giftWrap":false, "giftMessage":null, "customizable":false, "customizationPrompt":null, "customization":null, "returnDays":0, "shippingEstimatedDays":7, "SKU":"PROD-2016-07" } ], "packages":null, "shippingService":"EXPEDITED_1_DAY", "shippingAddress":{ "fullName":"Jane MoreCommerce", "address1":"152 W. 25th St.", "address2":"12th Floor", "city":"New York", "county":null, "state":"NY", "zip":"10001", "countryCode":"USA", "phoneNumber":null, "phoneExt":null } }, { "orderId":622475, "channel":"OPENSKY", "channelOrderId":"903377883", "channelSellerId":"55965b3b4b3d6fe0218b657d", "site":"OPENSKY", "status":"pending", "createdAt":"2016-08-03T10:04:11.000+0000", "shippingPrice":1, "handlingPrice":0, "tax":0, "giftWrapPrice":0, "discount":null, "subtotal":1, "total":2, "items":[ { "orderItemId":704550, "channelOrderItemId":"3799019", "productId":12344819, "channelProductId":"579f0bd5e22461022524b4b7", "name":"Sample Product Seven", "status":"pending", "quantity":1, "quantityShipped":0, "price":1, "shippingPrice":1, "handlingPrice":null, "tax":0, "taxRate":0, "taxShipping":false, "giftWrapPrice":null, "discount":0, "undiscountedPrice":1, "shippingPaid":null, "taxPaid":null, "weight":1, "giftWrap":false, "giftMessage":null, "customizable":false, "customizationPrompt":null, "customization":null, "returnDays":0, "shippingEstimatedDays":7, "SKU":"PROD-2016-07" } ], "packages":null, "shippingService":"ECONOMY_GROUND", "shippingAddress":{ "fullName":"Jane MoreCommerce", "address1":"152 W. 25th St.", "address2":"12th Floor", "city":"New York", "county":null, "state":"NY", "zip":"10001", "countryCode":"USA", "phoneNumber":null, "phoneExt":null } } ], "totalCount":2 }

Retrieve multiple orders by MoreCommerce internal order ids.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
orderIds array Array of MoreCommerce internal order ids (integers).
Max 100 order ids allowed. Order ids are provided in the Search Orders API call.
required

Internal order ids (orderId field in the Order object) need to be provided in the orderIds array. Listing/searching orders by channelOrderId is not possible.

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
orders object Array of Order objects.

Search Orders

Example request body:

{ "sellerId":12345, "page":1, "pageSize":100, "filters":[ { "field":"CHANNEL", "operator":"EQUAL", "value":"OPENSKY" }, { "field":"CREATED_AT", "operator":"GREATER_THAN", "value":"2016-05-01T10:16:27.000+0000" }, { "field":"STATUS", "operator":"EQUAL", "value":"canceled" } ] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "orders":[ { "orderId":622415, "channel":"OPENSKY", "channelOrderId":"903377644", "channelSellerId":"55965b3b4b3d6fe0218b657d", "channelBuyerId":"55c3719e4b3d6f6e288b5c19", "site":"OPENSKY", "status":"canceled", "shippingPrice":1, "handlingPrice":0, "tax":0, "giftWrapPrice":0, "discount":null, "subtotal":1, "total":2, "items":[ { "orderItemId":704485, "channelOrderItemId":"3798765", "productId":12344819, "channelProductId":"579f0bd5e22461022524b4b7", "name":"Sample Product Seven", "status":"canceled", "quantity":1, "quantityShipped":0, "price":1, "shippingPrice":1, "handlingPrice":null, "tax":0, "taxRate":0, "taxShipping":false, "giftWrapPrice":null, "discount":0, "undiscountedPrice":1, "shippingPaid":null, "taxPaid":null, "weight":1, "giftWrap":false, "giftMessage":null, "customizable":false, "customizationPrompt":null, "customization":null, "returnDays":0, "shippingEstimatedDays":7, "SKU":"PROD-2016-07" } ], "packages":[ { "orderPackageId":558873, "channelOrderPackageId":"2957773", "carrier":"usps", "trackingNumber":"7Fe2EmCwh3YQMrpK7Zla", "weight":null, "shippedAt":"2016-08-16T05:30:39.000+0000", "packageItems":[ { "orderItemId":704485, "quantity":1 } ] } ], "shippingService":"ECONOMY_GROUND", "shippingAddress":{ "fullName":"Jane MoreCommerce", "address1":"152 W. 25th St.", "address2":"12th Floor", "city":"New York", "county":null, "state":"NY", "zip":"10001", "countryCode":"USA", "phoneNumber":null, "phoneExt":null } } ], "totalCount":1 }

Retrieve a list of orders, optionally filtered by a condition.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
filters object Optional filters.
All conditions in the filter array have to match, filters are combined with the "AND" operator.
optional
filters.field string Supported search fields: CREATED_AT, CHANNEL, STATUS.
filters.operator string Supported operators: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IS_NULL.
filters.value object
page integer Page number (default 1). required
pageSize integer Number of records per page (default 100). required

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
orders array Array of Order objects.

Ship Orders

Example request body:

{ "sellerId":12345, "shipments":[ { "orderId":65484, "carrier":"usps", "trackingNumber":"7Fe2EmCwh3YQMrpK7Zla" } ] }

Example response body (200 OK):

{ "callReferenceId":"123ABCdefGHIjklmNOP0", "results":[ { "index":0, "orderId":65484, "status":"SUCCESS", "errors":null } ] }

Mark orders as shipped, in bulk, by providing tracking number information.

Request

Name Type Description Notes
sellerId integer MoreCommerce internal seller id (provided in the authentication response). required
shipments array Array of shipment objects. Provide carrier and tracking number to mark an orderId as shipped. required
shipments.carrier string required
shipments.orderId integer required
shipments.trackingNumber string required

Currently, the API allows only one shipment per order.The ship orders request allows a maximum of 100 shipments per API call.

The list of carriers currently accepted in MoreCommerce (updated December 2018):

Carrier Supported Names
USPS usps
Fedex fedex
UPS ups
DHL dhl
UPS Mail Innovations ups-mi, upsmi, upsmailinnovation
DHL eCommerce dhl-global-mail, dhlglobal, dhlgm, dhlglobalmail, dhlg, dhl-gm
Other other

Response

Name Type Description
callReferenceId string Unique response identifier (used for debugging/bug reporting).
results object Array of Order Result objects.

The OrderResult object has the following properties:

Name Type Description
index integer Index of the product in the request array. Starts from 0.
orderId integer The internal order id provided in the request.
status string Status of the ship order operation. Possible values: SUCCESS, FAILED.
errors array Array of Error objects.

Platform Notifications

Notification Classes

Orders

Notifications related to order events.

Method Description
POST /v1/SellerOrderCreatedOrUpdated Create and update order events.

Order Notifications

Create or Update Orders

Example:

{ "orders":[ { "orderId":101 }, { "sellerId":12002, "orderId":111 } ] }

Create and update order events.

Notifications are sent to the URL made up of the: notification base URL provided by the Partner plus the relative URL of the specific notification (/v1/SellerOrderCreatedOrUpdated in this case).

Order notifications are sent as event hints, the payload contains seller and order ids. This data be used with the Merchant API Get Order or List Orders calls to retrieve the current information about the order.

Payload

Parameter Type Description
orders JSON object array Array of Order objects. Min: 1 order, max: 50 orders.

The Order object has the following structure:

Parameter Type Description
sellerId integer MoreCommerce internal seller id (provided in the Merchant API integration).
orderId integer MoreCommerce internal order id (available in the Merchant API integration).