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
2023-09
Added
Custom handling time supported in product create and update calls (shippingDetails). Details about the MoreCommerce shipping service levels can be found here.
2023-08
Added
Additional ground shipping profiles in product create and update calls (shippingDetails). Details about the MoreCommerce shipping service levels can be found here.
Added
New attribute returned by Get, List and Search product calls, 'channels.opensky.liveStatus', represents the product's actual (resulted) status on MoreCommerce. Possible values: 'LIVE' and 'NOT_LIVE'. This attribute is searchable (check Search Products section for details).
Changed
Attribute 'channels.opensky.status' was changed to reflect the seller's intention of publishing the product (accepted values 'DRAFT' or 'PUBLISHED'), and not the product's actual (resulted) status. With this change 'FAILED' is no longer a possible value.
2022-08
Removed
'doesNotHaveIdentifiers' flag was removed from all product calls.
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:
- an API application key id - that needs to be passed with each request,
- a secret key - that is used for request signing.
Each Partner application should provide:
- an A&A success return URL - which should handle the parameters described below, in the A&A Seller Flow
- an A&A failure return URL - which should handle the errors described below, in the A&A Seller Flow
to be used on the seller authorization flows.
To use the MoreCommerce Platform Notifications, the Partner needs to provide:
- a notification base URL - to which platform events are notified.
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
- partnerSecretKey is the secret key provided on Partner registration,
and the
- stringToSign is composed of the request URI, request date, user key and message body, as detailed in the API Call Authorization section.
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:
- apiRequestDate and apiRequestKeyId are the values from the corresponding headers,
- apiRequestContent is the API call JSON content body,
- relativeApiCallURI is the relative API call URI (e.g. for a Get Order call, this would be
/bis-api/public/api/v1/orders/get).
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:
- the merchant clicks on a link on the Partner's site (the Entry Point)
- the merchant is directed to the MoreCommerce merchant login (currently on morecommerce.com), where they sign in with their MoreCommerce merchant account, and they either:
- authorize the Partner, in which case they are redirected back to the Partner's Success Return URL, or
- cancel the process, in which case they are redirected back to the Partner on the Failure Return URL.
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. All fields are case sensitive, they should be provided as listed in this documentation.
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 :
- number of new products created per month (default 500,000)
- number of product updates per day (default 100,000)
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", "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. SKUs cannot be updated via the API. |
| 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. |
| identifiers | object | One or more of the identifiers below. This is for simple products. Use variants.identifiers for products with variations - see the Variations object description. |
| 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 or Update calls, 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 (DEPRECATED) |
object | MoreCommerce sites to publish on. By default, all products are published on morecommerce.com. |
| status | string | The seller intended publish status for the product. Accepted values: DRAFT or PUBLISHED. (The DRAFT status can be used to hide products, delete operations are not supported.) |
| 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 (DEPRECATED) |
boolean | The product is sold exclusively on MoreCommerce. |
| maxDiscountPercentageLocked (DEPRECATED) |
boolean | See this help article for discounts. |
| maxProductDiscount (DEPRECATED) |
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 (DEPRECATED) |
integer | Ranking for the item placement within the merchant store page. |
The following properties of the product are read-only. They are not used and should not be sent in the Create or Update calls, but are returned in the Get, List and Search calls:
| Name | Type | Description |
|---|---|---|
| channels.opensky.liveStatus | string | The product's actual live status on MoreCommerce. Possible values: LIVE or NOT_LIVE. |
| channels.opensky.errors | array | The product's publish errors. Array of strings. |
| channels.opensky.warnings | array | The product's publish warnings. Array of strings. |
| channels.opensky.productURL | string | The product's URL on MoreCommerce warnings (returned only when liveStatus is LIVE). |
Snippet from the Create Product call, with a shipping details JSON example:
{... "shippingDetails":{ "profiles":[ { "service":"ECONOMY_GROUND", "handlingTime":5, "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:
Use this object (instead of channels.opensky.shippingDetails) to define ground and expedited shipping profiles. Details about the MoreCommerce shipping service levels can be found here.
| 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, STANDARD_4_DAY_GROUND, STANDARD_3_DAY_GROUND, ECONOMY_GROUND, FREIGHT_GROUND, INTL_GROUND, EXPEDITED_1_DAY,
EXPEDITED_2_DAY. Only one ground service (either STANDARD_GROUND, STANDARD_4_DAY_GROUND, STANDARD_3_DAY_GROUND, ECONOMY_GROUND, FREIGHT_GROUND or INTL_GROUND) is required,
and none or any of the expedited services can be specified.
|
| profiles[].handlingTime | number | Optional number of days until shipping, if different than the service default. Accepted values: STANDARD_GROUND: 0-3, STANDARD_4_DAY_GROUND: 0-2, STANDARD_3_DAY_GROUND: 0-2, ECONOMY_GROUND: 0-5, FREIGHT_GROUND: 0-10, INTL_GROUND: 0-5. Not available for EXPEDITED_1_DAY and EXPEDITED_2_DAY.
|
| 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.SKUs cannot be updated via the API. |
| 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:
- SKU
- name
- description
- price
- quantity
- images
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 }, "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":{ "status":"PUBLISHED", "category":"accessories/baby-toddler-accessories/baby-toddler-bags", "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.", "liveStatus":"LIVE", "errors":null, "warnings":null, "productURL":"https://www.morecommerce.com/mystorename/product/sample-product-two" } }, "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":{ "status":"DRAFT", "category":"accessories/baby-toddler-accessories/other-baby-toddler-accessories", "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.", "liveStatus":"NOT_LIVE", "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":{ "status":"PUBLISHED", "category":"Other", "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, "liveStatus":"NOT_LIVE", "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.", ], "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":0, "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":{ "status":"PUBLISHED", "category":"accessories/other-accessories", "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, "liveStatus":"NOT_LIVE", "errors":null, "warnings":[ "Inventory required to publish product" ], "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":{ "status":"PUBLISHED", "category":"Other", "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":"NOT_LIVE", "errors":null, "warnings":[ "shippingPrice: This value should be a valid number.", "secondaryShippingPrice: This value should be a valid number.", "Please choose a category.", ], "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 | integer | Page number | required |
| pageSize | integer | Page size (max 100) | 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, OPENSKY_LIVE_STATUS |
|
| filters.operator | string | Supported operators: EQUAL, IS_NULL |
|
| filters.value | string | Supported values for OPENSKY_STATUS: DRAFT, PUBLISHEDSupported values for OPENSKY_LIVE_STATUS: LIVE, NOT_LIVE |
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. |
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:
- X-OPENSKY-PUBLIC-API-USER-KEY-ID header is not required (and is ignored if present)
- userKeyId is not included in the formula to calculate the request signature, which becomes:
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, STANDARD_4_DAY_GROUND, STANDARD_3_DAY_GROUND, ECONOMY_GROUND, FREIGHT_GROUND, INTL_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. |
| trackingLink | string | Tracking link. |
| 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 | required |
| pageSize | integer | Page size (max 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 | |
| shipments.trackingLink | string |
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). |