NAV
shell js

Introduction

Welcome to the RetailCloud API v2! The API provides the ability to create products, add variants, update inventory and cost for existing products, retrieve orders, retrieve purchase orders, and update tracking. You may implement all or only a portion of the API depending on your needs.

We do not have pre-built SDK’s, but the API is designed for JSON over HTTP and should be easily implemented in any modern programming language! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. We recommend that you test your access and results with curl or Postman before beginning development. This will ensure that your access and baseURL are setup correctly.

Your use of this API is subject to the vendor contract. Any data submitted or changed via API is binding upon the vendor per the terms of that contract.

Base URL

Our API maintains separate systems for staging and production with a portal and API running in each environment. Please make sure you use the correct combination of base URL and portal as the API will only accept tokens from the matching portal.

Development Process

The staging environment allows you to develop and test your code without impacting any production operations as the environment is completely separate. To begin:

  1. Request staging portal credentials from your Buyer and ask them to enable the V2 API for you.
  2. Login to https://admin-staging.retailcloud.io and navigate to the vendor profile page. If the API is properly enabled you will see a green and red button on the top of the page which allows you to generate a token and invalidate existing tokens. Please click on the generate token button and make a secure note of the Authorization token provided.
  3. Using Postman or CURL test your access by making a GET request to https://api-staging.retailcloud.io/v2/products. You will need to set your authorization to “Bearer” and add the token from step 2 as well as specifcying a header of Content-Type: application/json.
  4. You will likely receive an empty result unless you’ve created a product in the admin, but as long as you receive a 200 Status response, you have validated your confirm. A 403 indicates that your request failed due to authorization issues. In this case, confirm that you are matching the staging API with the staging portal in creating tokens.
  5. You may wish to create manually created a product in the portal using the Product Wizard and repeat the above request to ensure you are getting data correctly.
  6. At this point, you should begin your development work to integrate with your internal systems. Please see the endpoint specific documentation for assistance in this process.
  7. Once you have products in your staging environment either created via the API or manually using the wizard, please request your Buyer to publish and create orders from our staging store. This process follows the same workflow as our production environment. At this point, you may continue development on the order portions of the API.

Moving to Production

Once your develoopment work is complete, please notify your Buyer and request that they activate the V2 API in production. After they make this update, you will see the same token generation buttons in the vendor profile at https://admin.retailcloud.io. Obtain a new product token and modify the endpoint and token in your environment to point to the production API at https://api.retailcloud.io.

Authentication

# With shell, you can just pass the correct header with each request.

curl "https://my_base_url/v2/api_endpoint_here"
  -H "Authorization: Bearer my.sectet.token"
const Axios = require('axios');  

const requestObject = {
  url: "api_endpoint_here",
  method: 'get',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  }
};

const responseObject = await Axios(requestObject);

Make sure to replace my.secret.token with your API key.

UntilGone uses bearer tokens to allow access to the API. See the development process for instructions on how to obtain a token for the appropriate environment.

The API token must be included in all API requests to the server in a header that looks like the following:

Authorization: "Bearer my.secret.token"

Please refer to the documentation for your language and HTTP request package for adding a header to a request. Most will include explicit documentation on the Authorization header and in particular the Bearer version of it that uses JWT tokens.

Products

retailcloud.io does not operate as a marketplace where the vendor sets the final price, but rather is a Daily Deal site. As such, UntilGone controls what products are published to our front-end and at what retail price. In the following models and API’s, you will be able to create the product and variants, but these will be held in an “offered” status until one of our buyers decides to publish the product. In the GET products API below, the model and response includes a published field which denotes whether the product is published to the front-end eCommerce site (True) or not (False).

If you wish to remove a product from the site, please update the inventory to 0. This won’t delete the product, but it will eventually be removed from the front-end and will stop sales as soon as the update processes.

Product Data Models

Our product models are intentionally similar to the Google Merchant Center data feed specification. In many cases, if you already have a data feed/mapping to create data for Merchant Center then your data should be easily usable with the UntilGone API. If you have questions about field definitions, please refer to the Google specification (e.g. color, categories, size_type, etc.)

Product Model

Field Type Required? Description
published boolean Only appears in responses and indicated if a product is published to the site.
title String true Minimum 10 characters. We recommend up to 80.
category String true We use the Google Category tree exclusively. If your system doesn’t already support this taxonomy, please download the relevant file at the link provided. At minimum, please enter the top level category (e.g. Apparel & Accesories or Electronics). Ideally, enter a 3 level tree.
brand String true
condition String (Enum) true Accepted values: New, Factory Refurbished, Refurbished, Used, Junk, Mixed
conditionDetail String Short description of the condition (e.g. Open Box, Grade A, etc.)
description String true Product Description
modelNumber String
features Array (String) An array of features for this product. These will be displayed as a bullet list on the storefront.
variants Array (Object) true Refer to the variant model
options Array (String) false For multi-variant products, specifies the option type (e.g. Size, Color) that corresponds to the same order as the option field in the variant.
warranty Object true Refer to the warranty model
specifications Array (String) Array of product specifications used in the description on the storefront.
inTheBox Array (String) Array of items included in the package
primaryImageURL String true A valid image url, UntilGone will download that image and save it in the file system. Dropbox links do not work.
secondaryImageURL Array (String) One or more URL’s to valid images

Variant Model

Field Type Required? Description
title String true Variant identified (e.g. XL Blue)
sku String true Vendor’s SKU - should be unique
shipping Object true Refer to the Shipping Dimensions Model
msrp Number true Manufacturer’s Suggested Retail Price
price Number true Suggested Retail Price (retailcloud.io will set the final selling price)
cost Number true Amount to be paid to vendor for product
option Array (String) false Variant options (e.g. [“Small”, “Red”]). Should correspond to the same order as the options field at the product level. The combination of option values should be unique for all variants.
upc Number GTIN or UPC are strongly suggested to maximize sales
mpn Number Always provide the model/part number if avaialable
color String sometimes Required for Apparel, optional otherwise
size String sometimes Required for Apparel, optional otherwise
size_type String Optional for Apparel, not otherwise Refer to Google Merchant Center data specification
size_system String Optional for Apparel, not otherwise Refer to Google Merchant Center data specification
pattern String sometimes Required for Apparel, optional otherwise
material String sometimes Required for Apparel, optional otherwise
age_group String sometimes Required for Apparel, optional otherwise
gender String sometimes Required for Apparel, optional otherwise (male, female, unisex)
image String URL to image for this variant

Warranty Model

Field Type Required? Description
phoneNumber String Phone number for warranty requests
email String Email for warranty requests
url String URL of website for customer to request warranty service
duration String Length of warranty (Enum of “30 Day Warranty”,”90 Day Warranty”, “90 Day Manufacturer Warranty”, “1 Year Manufacturer Warranty”,”2 Year Manufacturer Warranty”)
provider String Usually specifies vendor, distributor or manufacturer

Shipping Dimensions

Field Type Required? Description
width* Number true Width in inches, Maximum 108
height* Number true Width in inches, Maximum 108
depth* Number true Width in inches, Maximum 108
weight Number true Weight in lb

Get All Products

const Axios = require('axios');

const requestObject = {
  url: "/v2/products",
  method: 'get',
  baseURL: 'https://base_url',
  params: {
    limit: 1000,
    page: 1
  },
  headers: {
    `Authorization`: `Bearer my.secret.token`
  }
};

const responseObject = await Axios(requestObject);

curl "https://<base_url>/v2/products"
  -H "Authorization: Bearer my.secret.token"

The above command returns JSON structured as an array of objects:

[{
   "published": true,
   "title": "Your product title",
   "stores": [
    {
      "url": "https://mystore.com/product/this-is-the-product.html",  // this is the URL to the store
      "status" true  // this is whether is is live on this particular store
    }
   ],
   "variants": [{
     "sku": "VARIANT_SKU", // this is the sku your company created for your products
     "ugSKU": "UNTIL_GONE_VARIANT_SKU_1", // this is the sku that UntilGone creates for your products
     "title": "Variant Title",
     "shipping": {
       "width": 1,
       "height": 1,
       "depth": 1,
       "weight": 1
     },
     "msrp": 25,
     "price": 20,
     "cost": 13.25,
     "inventory": 10
   }]
 },
 {
   "published": false,
   "title": "Second product title",
   "stores": [
    {
      "url": "https://mystore.com/product/this-product.html",
      "status" true
    },
    {
      "url": "https://adifferentstore.com/product/this-same-product.html",
      "status" true
    }
   ],
   "options: ["Size", "Color"],
   "variants": [{
     "sku": "VARIANT2_SKU",
     "ugSKU": "UNTIL_GONE_VARIANT_SKU_2",
     "title": "Variant Title",
     "shipping": {
       "width": 2,
       "height": 2,
       "depth": 2,
       "weight": 3
     },
     "option": ["Large", "Purple"]
     "msrp": 25,
     "price": 20,
     "cost": 13.25,
     "inventory": 10
   },{
     "sku": "VARIANT3_SKU",
     "ugSKU": "UNTIL_GONE_VARIANT_SKU_3",
     "title": "Variant Title",
     "shipping": {
       "width": 2,
       "height": 2,
       "depth": 2,
       "weight": 3
     },
     "option": ["Medium", "Green"]
     "msrp": 25,
     "price": 20,
     "cost": 13.25,
    ]
 }
]

This endpoint retrieves all products with query string paramters to control page size and pagination. The default page size is 10,000 products due to the fact that at least one major system was unable to handle pagination. For most users, we recommend setting a limit of 1000 and then paginating through the result set.

HTTP Request

GET https://<base_url>/v2/products

Query Parameters

Parameter Default Description
limit 10000 Returns up to 10000 products per page.
page 1 The page to return.

Create/Update Product

const Data = arrayOfProductObjects;  // see example request body below

const Axios = require('axios');

const requestObject = {
  url: "/v2/products",
  method: 'post',
  baseURL: 'https://base_url',
  params: {
    limit: 1000,
    page: 1
  },
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -d '{json request body}' "https://<base_url>/v2/products"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Example of a request body. This is a JSON array of objects. Please refer to the data models for specifics.

[{
 "title": "The title of the product",
 "category": "Apparel & Accessories > Jewelry > Anklets",
 "brand": "test brand",
 "condition": "New",
 "conditionDetail": "Open Box",
 "description": "This is the product description",
 "modelNumber": "test model",
 "features": ["feature1", "feature2", "feature3"],
 "options": ["Size", "Color"],
 "variants": [{
   "sku": "VAR01SKU",
   "title": "The variant title",
   "shipping": {
     "width": 1,
     "height": 1,
     "depth": 1,
     "weight": 1,
     "weightUnit": "lb"
   },
   "option": ["Small", "Red"],
   "msrp": 10,
   "upc": "this is primary",
   "mpn": "this is secondary",
   "price": 6,
   "srp": 8,
   "inventory": 10,
   "cost": 1
 },{
   "sku": "VAR01SKU-BLUE",
   "title": "The variant title for variant 2",
   "shipping": {
     "width": 1,
     "height": 1,
     "depth": 1,
     "weight": 1,
     "weightUnit": "lb"
   },
   "option": ["Small", "Blue"],
   "msrp": 10,
   "upc": "this is primary",
   "mpn": "this is secondary",
   "price": 6,
   "srp": 8,
   "inventory": 10,
   "cost": 1
 }],
 "warranty": {
   "phoneNumber": "123123123",
   "emailAddress": "test@email.com",
   "url": "test/url",
   "duration": "30",
   "provider": "test provider"
 },
 "specifications": [{
     "name": "Spec1",
     "value": ["val1", "val2", "val3"]
   },
   {
     "name": "Spec2",
     "value": ["val4", "val5", "val6"]
   }
 ],
 "inTheBox": ["box1", "box2", "box3"],
 "primaryImageURL": "primary image url",
 "secondaryImageURLs": [
   "other image url",
   "other image url",
   "other image url"
 ]
}]

Example of a response body. 

{
 "errors": [],
 "created": [
     {
        "variants": [
             {
              "sku": "VAR01SKU",
                  "ugSKU": "SKU99999"
             }
         ],
         "title": "The title of the product"
     }
 ],
 "createdCount": 1,
 "ignoredCount": 0,
 "issues": 0
}

This endpoint is used to create a product. If a product remains in offered status, you may continue to update the product using this endpoint. Once the product is no longer in offered status, updates will only update suggested retail price, cost, and inventory which are better managed via the inventory endpoint.

You may send a MAXIMUM of 250 product per request. Items beyond 250 will be dropped and ignored.

HTTP Request

POST http://<api_endpooint>/v2/products

URL Parameters

None

Errors

Any error found when inserting a product, will return in the errors array and the product containing that error will not be created. Products with validation problems will not affect other products, if any incorrect product is found and not created, the rest of them will be created normally.

Error example is shown in the sidebar.

{
 "errors": [
     {
         "message": "Invalid title, it must contain at least 3 characters",
         "code": "200",
         "title": "The title of the product",
         "sku": [
             "VAR03SKU"
         ]
     }
 ],
 "created": [],
 "createdCount": 0,
 "ignoredCount": 0,
 "issues": 2
}

Add Variants

const Data = arrayOfVariantObjects;  // see example request body below

const Axios = require('axios');

const requestObject = {
  url: "/v2/variants",
  method: 'post',
  baseURL: 'https://base_url',
  params: {
    limit: 1000,
    page: 1
  },
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -d '{json request body}' "https://<base_url>/v2/variants"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Example request body:

{
 "sku": "VARIANT_SKU_02", // this is the sku from any variants of the product, it's used to find the product to add more variants
 "variants": [{ // the array of new variants for the product
     "sku": "VARIANT_SKU_03333",
     "title": "your new variant name",
     "shipping": {
       "width": 1,
       "height": 1,
       "depth": 1,
       "weight": 1
     },
     "option": ["Small", "Blue"],
     "msrp": 10,
     "srp": 10,
     "upc": "upc",
     "mpn": "mpn",
     "price": 6,
     "cost": 1,
     "inventory": 1,
     "sale": 5
   }
 ]
}

Sample response body:

{
 "errors": [],
 "createdCount": 2,
 "ignoredCount": 0,
 "issues": 0
}

This endpoint allows you to add variants to existing products that were not in the initial product create. In general, this will not be used frequently as its easeier to add the variants at the time the product is created. However, this is useful when a new option becaomes available such as a different color or size that was not initially availble.

You can add multiple variants to a single product in each request. The request body requires a variant sku for an existing variant of the product you are trying to edit and an array of new variants to be added to that product.

There is a maximum limit of 100 variants for any given product.

HTTP Request

GET http://<api_endpooint>/v2/variants

URL Parameters

None

Errors

Any error found when inserting a product, will return in the errors array and the product containing that error will not be created. Products with validation problems will not affect other products, if any incorrect product is found and not created, the rest of them will be created normally.

Error example is shown in the sidebar.

{
 "errors": [
     {
         "message": "One or more SKU values already exist in our database",
         "title": "This is the product title",
         "id": "5c6b273fac36a21c7aae02a3",
         "sku": [
             "VARTEST01",
             "VARTEST02"
         ]
     }
 ],
 "createdCount": 0,
 "ignoredCount": 0,
 "issues": 1
}

Inventory

This endpoint allows for updates to inventory as well as cost on a variant level. The SKU used is the vendor SKU that you provided at the time the product was created. It does not matter if the product is created via the Wizard, by our copywriters or via API as the update will be applied to anything that matches this vendor SKU in your product list.

Inventory Data Model

Once a product moves out of offered status, you will only be able to maintain the following data. Changes to cost may impact the product availability as the system currently removes any product where the cost is increased until such time as the pricing can be reviewed by the assigned buyer.

If you wish to stop sales of the product, set the inventory (availability) to 0. You will need to do this for each SKU.

Please make sure you check for existing released orders prior to modifying your inventory. Our system will automatically adjust inventory for any orders that have not yet been released to fulfillment, but we assume you are accounting for any orders that your system has retrieved.

Field Type Required? Description
sku String true The SKU identifier used in your inventory tracking system
available Number Quantity available
price Number Suggested retail price
cost Number The cost of the item. Cost increases will remove the product from site until approved.

Update Inventory

const Data = arrayOfInventoryUpdates;  // see example request body below

const Axios = require('axios');

const requestObject = {
  url: "/v2/inventory",
  method: 'put',
  baseURL: 'https://base_url',
  params: {
    limit: 1000,
    page: 1
  },
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -X PUT -d '{json request body}' "https://<base_url>/v2/inventory"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Sample request body:

[{
  "sku": "PROD01SKU",
  "available": 5,
  "price": 11,
  "cost": 5
},
{
  "sku": "PROD02SKU",
  "available": 6,
  "price": 6,
  "cost": 6
}]

Sample response body:

{
 "status": true,
 "result": {
     "status": true,
     "updated": 2,
     "errors": []
 }
}

This endpoint is used to update inventory, cost or suggested retail price by variant. It updates any variant matching the vendor SKU in your product list regardless of how that product was created.

HTTP Request

PUT https://<base_url>/v2/inventory

Query Parameters

None

Errors

Any error found when updating the inventory and prices, will return in the errors array and the product containing that error will not be updated.

Error example is shown in the sidebar.

{
 "issues": 1,
 "updated": 0,
 "errors": [
     {
         "message": "Field sku is missing",
         "code": "200"
     }
 ]
}

Orders

We recommend the minimum implementation is Get Orders and Fulfill Orders. This enables your system to retrieve orders and add tracking information back to orders. By default, the Get Orders endpoint does not return any orders which have already been shipped. Refer to the query parameters if you want to get all orders including those which shipped in the past.

The “uli” paramater is being replaced by “uiid”. Both will carry the same information going forward, but eventually the ULI parameter itself will be removed. Please use UIID wherever possible.

Get All Orders

const Axios = require('axios');

const requestObject = {
  url: "/v2/orders",
  method: 'get',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  }
};

const responseObject = await Axios(requestObject);

curl "https://<base_url>/v2/orders"
  -H "Authorization: Bearer my.secret.token"

Sample response object:

[{
 "uli": "UG1-123456789",  // deprecated, use UIID instead
 "uiid": "UG1-123456789",
 "company": "Company",
 "name": "Name",
 "address1": "Address 1",
 "address2": "Suite 123",
 "city": "City",
 "state": "State",
 "zip": "Zip",
 "country": "United States",
 "phone": "555-4444",
 "ugSKU": "SKU179703",
 "sku": "FL-NR15-R24-OLI-PS",
 "quantity": 1,
 "description": "Description",
 "cost": 8.3,
 "orderDate": "2019-01-29T17:22:00.864Z",
 "po": "100471",
 "personalized": true,
 "personalization: [
  {
    "label": "team name",
    "value": "Seahawks"
  },
  {
    "label": "childs-name",
    "value": "Jennifer"
  }
 ]
}]

This endpoint returns orders. The “uiid” number is the unique order identifier for vendor orders used across our system. The UIID should be treated as a string value as the format may change. Each UIID or vendor order will contain only one product for one customer. If you happen to receive more than one UIID for a given customer, you may combine shipments (e.g. customer orders two variants of the same shirt in different colors), but these will be sent as separate UIID’s.

The “uli” paramater is the older format and is being replaced by “uiid”. Both will carry the same information going forward, but eventually the ULI parameter itself will be removed. Please use UIID wherever possible.

HTTP Request

GET https://<base_url>/v2/orders

Query Parameters

Parameter Default Description
start_date The starting date range of orders to request
end_date The ending date range of orders to request.
incShipped false Whether to include orders that have already been shipped. Parameter value does not matter. Including it in the query string results in shipped orders showing. Omit it to just see un-shipped.

We recommend you use an ISO8601 date format such as 2022-01-01T08:00:00-07:00, but you can shorten that to 2022-01-01 and still get valid results. Please note that we will convert any date to Pacific Time so if you do not use a full ISO date with timezone, your time window may not be exactly what you expect as it is initially parsed as GMT time and then converted before the query is run.

Get Purchase Order

const Axios = require('axios');

const requestObject = {
  url: "/v2/po",
  method: 'get',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  }
};

const responseObject = await Axios(requestObject);

curl "https://<base_url>/v2/po"
  -H "Authorization: Bearer my.secret.token"

Sample response object:

{
 "status": true,
 "result": {
   "po": "100471",
   "uli": [       // deprecated, use UIID instead
     123456789
   ], 
   "uiid": [
     "UG1-123456789"
   ]
 }
}

This endpoint returns Purchase Order Info. Any individual order will have a unique UIID number that identifies it. PO’s are issued each business day for orders from the preceding period. The API allows for associating a UIID with a given PO for accounting purposes and is entirely optional as a convenience method; however, for those looking to automate accouting the PO is critical as we use that for payment purposes.

We are eliminating the ULI numbers going forward, but for backwards compatibility we are including it. Please use UIID going forward for everything.

HTTP Request

GET https://<base_url>/v2/po

Query Parameters

Parameter Default Description
uiid required The UIID to lookup
uli required The ULI to lookup. DEPRECATED.

Acknowledge Orders

const Axios = require('axios');

const Data = arrayOfOrderAcks;

const requestObject = {
  url: "/v2/orders/ack",
  method: 'POST',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -X PUT -d '{json request body}' "https://<base_url>/v2/orders/ack"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Sample request body:

[{
 "uli": "123456789",  // deprecated, use UIID
 "uiid": "UG1-123456789",
 "expectedShipDate": "2018-11-27 18:15:11"
}]

Sample response object:

[{
 "uli": "123456789",  // deprecated, use UIID
 "uiid": "UG1-123456789",
 "status": "accepted"
}]

This endpoint is used to acknowledge orders as received and enter an expected ship date. This is not a required step in the order flow, but is beneficial to confirm that your system has received the order and that it is in process.

ULI is being deprecated. Please use UIID.

HTTP Request

GET https://<base_url>/v2/orders/ack

Query Parameters

None

Fulfill Orders (Add Tracking)

const Axios = require('axios');

const Data = arrayOfFulfillments;

const requestObject = {
  url: "/v2/orders/fulfill",
  method: 'POST',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -X PUT -d '{json request body}' "https://<base_url>/v2/orders/fulfill"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Sample request body:

[{
   "uli": "UG1-123456789",  //deprecated use UIID
   "uiid": "UG1-123456789",
   "tracking": {
     "number": "AAA2223333WW2",
     "date": "2019-02-27 18:15:11",
     "carrier": "Carrier"
   }
 },
 {
   "uli": "UG1-987654321",  // deprecated use UIID
   "uiid": "UG1-987654321",
   "tracking": {
     "number": "AAA2223333WWW",
     "date": "2019-02-27 18:15:11",
     "carrier": "Carrier"
   }
 }
]

Sample response object:

{
 "status": true
}

This endpoint updates order fulfillments and adds the tracking number as well as confirms that it has shipped.

HTTP Request

POST https://<base_url>/v2/orders/fulfill

Query Parameters

None

Cancel Order

const Axios = require('axios');

const Data = cancelItemObject;

const requestObject = {
  url: "/v2/orders/cancel",
  method: 'POST',
  baseURL: 'https://base_url',
  headers: {
    `Authorization`: `Bearer my.secret.token`
  },
  data: Data
};

const responseObject = await Axios(requestObject);

curl -X PUT -d '{json request body}' "https://<base_url>/v2/orders/fulfill"
  -H "Authorization: Bearer my.secret.token" 
  -H "Content-Type: application/json"

Sample request body:

{
  "uli": "UG1-123456789",  //deprecated use UIID
  "uiid": "UG1-123456789",
  "audit": "cancel per John",
  "cancelNote": "Out of Stock"
}

Sample response object:

{
 "status": "success",
 "resultCode": 200,
 "resultMessage": "Cancellation and refund processed successfully!"
}

This endpoint is used to cancel a specific line item. Please use uiid going forward as ULI is deprecated.

HTTP Request

POST https://<base_url>/v2/orders/cancel

Query Parameters

None

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed
401 Unauthorized – Your API key is wrong. This is likely a mismatch between staging and production.
403 Forbidden – Your API key is wrong. This is likely a mismatch between staging and production.
404 Not Found – The specified item could not be found
405 Method Not Allowed – You tried to access an endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

FAQ

I’m getting a 403 error.

The number one reason we see developers with this error is a mis-match between their endpoint and their token. A token created in the staging portal can only be used with the staging API and a token created in the production portal can only be used in the production API. Please see the Base URL section in the intro for guidance on endpoints. We recommend that you use Postman or Curl to test your connection to eliminate any codition issues.

Do I need to check for 429’s (rate limiting)?

No, the API is implemented using cloud functions that will scale rapidly based on requests. We currently do not see any volume related issues, but we do reserve the right to implement rate limiting in the case of abusive behaviour.

I’m receiving an error when …

As a first step in diagnosing any issues, please use Postman to make the same request. This eliminates any code implementation issues. If you still find an error (and it’s not a 403), check the request body and headers you are using. A missing bracket or comma can cause a bad response so simplify the request as much as possible. If you are still unable to resolve the issue, send a copy of the request, your headers, and the body if any that is resulting in the error to us along with the date/time that you were testing and the complete error response. (This enables us to review our logs.)

I’m trying to update a product and nothing is happening.

API users can only update a product if it is still in “Offered” status. If it has been reviewed/approved/published by our team, you will be limited to update cost, inventory and suggested retail. Please login to the portal and check the status of the product you are trying to edit to see if this is the issue.

shell js