Tap for Menu

Introduction

API Endpoint:

https://api.convictional.com
https://api.convictional.com/(resource)/(id)
https://api.convictional.com/(resource)/(query)
https://api.convictional.com/(action)

Welcome to the Convictional API. You can use our API to access various resources on the Convictional platform. We use this API (and this document) to build our own applications.

Our goal providing an API for our service is to allow technically inclined customers to take advantage of the infrastructure, business rules, integrations and admin capabilities of our platform.

Versioning

Last Updated:

{
  "2018-06-08"
}

When breaking changes happen, we will notify users and migrate you. Our long-term goal is stability: EDI is not something that changes very often and custom fields can be used for anything customer-specific.

Authentication

Request Headers:

{ 
  "Authentication": "5ba82897-0bff-4e4e-842e"
}

Convictional uses API keys to authenticate your requests. When you register, we generate a key for you. To find your key, login to Convictional and go to "Settings". Include your API key in the "Authorization" header to authenticate your request and access your account. If you need a refresh, contact support.

Bulk Endpoints

Request Body (JSON):

[
  {},
  {},
  {},
  ... up to 97 more records.
]

Convictional offers bulk create/update and read endpoints. You can create/update up to 100 records at once, and read up to 500. The max request/response size is 6mb. Our client library handles queuing of requests, so we recommend it if you plan to do a lot of bulk requests.

Client Libraries

Require Statement:

// Top of your file with all your requires:
var convictional = require('convictional')({
  'apiKey': '86e7ccdc-55b5-4066-a79f-7a1e0e59c690'
})

// ... later where you want to use it:
var orderId = '5a692f658f6d524e8282dac7'
convictional.getOrder(orderId).then((order) => {
  // Do stuff with this particular order
}).catch((error) => { console.error(error) })

convictional.getOrders({}).then((orders) => {
  // Do stuff with all your orders
}).catch((error) => { console.error(error) })

Convictional offers a client library for Node.JS. For more information visit the libary on NPM.

The client library will validate your request, check to make sure the right data is provided and throw a useful error if not. We use it to write all of our customer-specific applications, so you can trust it will continue to stay up to date with API changes.

It will also handle queueing of bulk requests so you can make one call for an unlimited number (limited by your machine's memory) of records. All endpoints can be accessed through the client library.

Responses

200: Returns (String):

{
  "OK"
}

400: Returns (String):

{
  "Not found"
}

401: Returns (String):

{
  "Not authorized"
}

500: Returns (String):

{
  "Bad request"
}

The Convictional API uses the following response codes:

Code Description
200 OK: means your request was successful.
307 Redirect: means this handler wants you to go somewhere else.
400 Not found: means the ID or code of the resource cannot be found.
401 Not authorized: means the "Authorization" header API kye is wrong.
500 Bad request: means something about your request body isn't right.

Custom Data

Schema:

{
  "_id": "ObjectID",
  "key": "string",
  "type": "string",
  "value": "string"
}

Example:

[
  {
    "_id": "5425345jh43lkh25jk",
    "key": "api_key",
    "type": "string",
    "value": "123ABC-DEF456"
  },
  {
    "_id": "5425345jh43lkh25jk",
    "key": "status_code",
    "type": "number",
    "value": "123"
  },
  {
    "_id": "5425345jh43lkh25jk",
    "key": "product_data",
    "type": "json",
    "value": "{ code: ABC, quantity: 3 }"
  }
]

Convictional allows use of custom key/value pairs on all resources. The three types we currently support are: strings, numbers and arbitrary JSON. All three will be stored as strings but you can convert them into the right type based on what is in the type field when you need to use it.

Data Types

{
  "string": "string",
  "number": 0,
  "json": { "this_is": "json" },
  "boolean": true,
  "date": "2018-05-31T18:03:24+00:00"
}
Type Description
string A string can be any length and contain alphanumberic characters
number A number can be any size and contain numberic characters
json A JSON object can contain arbitrary JSON
boolean A boolean is either true or false
date A date in ISO 8601 format ("YYYY-MM-DDThh:mm:ss.sss-hh:mm")

Actions

Action-oriented (RPC) endpoints that allow you to translate EDI documents, transmit files over FTP, invite your trading partners, run sync workers and more.

Sync

Returns (JSON):

{
  "Successfully pushed getOrders to queue"
}

This endpoint allows you to initiate a sync method of your choosing.

Sync Endpoint

https://api.convictional.com/sync/:method

Sync Example

GET https://api.convictional.com/sync/getOrders

Sync Methods

Method Description
getOrders Get the orders from all your trading partners
getOrderUpdates Get order updates from your system
postOrders Push orders from Convictional into your system
postOrderUpdates Push order updates to all your trading partners
getProducts Get products from your system
postProducts Push products to your trading partners
getProductUpdates Get inventory from your system
postProductUpdates Push inventory to your trading partners
postInvoices Invoice and charge for shipped orders
getSkuById Get SKU ID in attached partner shops

Translate

Returns (JSON):

{
  "segmentID": {
    "0": "first_element_value",
    "1": "second_element_value",
    "2": "third_element_value"
  },
  "segmentID": [
    {
      "0": "first_element_value",
      "1": "second_element_value",
      "2": "third_element_value"
    },
    {
      "0": "first_element_value",
      "1": "second_element_value",
      "2": "third_element_value"
    }
  ]
}

This endpoint allows you to convert an X12 EDI document in raw text into JSON.

Translate Endpoint

https://api.convictional.com/translate

Translate Example

POST https://api.convictional.com/translate

Translate Properties

Property Description
body The request body must contain an X12 EDI document in text

Query Parameters

Property Type Required Description
raw Boolean Optional Return raw document (default: true)

Transmit

Request (JSON):

{
  "fileName": "folder.fileName.txt",
  "document": "This is the contents of the file.",
  "credentials": {
    "host": "127.0.0.1",
    "port": "21",
    "user": "anonymous",
    "pass": "@anonymous"
  }
}

Success Returns (JSON):

{
  "status": "completed"
}

Failure Returns (JSON):

{
  "error": "No document provided."
},
{
  "error": "No file name provided."
},
{
  "error": "No credentials provided."
},
{
  "error": "(other connection errors)"
}

This endpoint allows you to send a document via FTP with provided credentials and file name.

Transmit Endpoint

https://api.convictional.com/transmit

Transmit Example

POST https://api.convictional.com/transmit

Transmit Properties

Property Type Required Description
fileName string Required The name of the file. For folders, put 'folder.folder.file.txt'
document string Required The contents of the document in plain text. Any format.
credentials json Required The credentials of the FTP server you want to send this to.

Credentials Properties

Property Type Required Description
host string Required The hostname or IP address of the FTP server.
port string Required The port of the FTP server.
user string Required Username for authentication.
pass string Required Password for authentication.

Invite

Request (JSON):

{
  "email": "test@convictional.com",
  "companyName": "Supplier, Inc.",
  "billing": true
}

Returns (JSON):

{
  "Invited partner: test@convictional.com"
}

This endpoint invites a single partner by email.

Invite Endpoint

https://api.convictional.com/partners/invite

Invite Example

POST https://api.convictional.com/partners/invite

Message example


Subject: You are invited to trade with: supplier

Body:
You are invited to trade with: supplier

1. Click the link below and make an account.
2. Then go to settings and connect to your store.

https://app.convictional.com/sign_up?billing=true&shop=supplier

Invite Properties

Property Type Required Description
email string Required The email of the partner you want to invite.
companyName string Optional Your company name so your partners recognize it.
billing boolean Optional Default: true. Do you want to get a credit card on file?

Orders

REST endpoints that allow you to create, retrieve, update and delete orders.

Order Properties

Property Type Required Description
_id String Automatic ID of this record
code String Required Retailer's order number
parentCode String Required Supplier's order number
posted Boolean Automatic Has this order been synced with your system?
shipped Boolean Automatic Has this order been shipped?
billed Boolean Automatic Has this order been invoiced?
complete Boolean Automatic Has this order been synced to your partner?
partner String Required The partner code that sent this order
date String Required The date of the order (YY/MM/DD hh:mm:ss)
items Array Required Contains all order items (products, tax, shipping)
fulfillments Array Optional Contains all in and out shipments
addresses Array Optional Contains all the customer addresses
custom Array Optional Custom key/value pairs
live Boolean Automatic True for live mode, false for test mode
created Date Automatic Date record was created (in ISO8601 format)
updated Date Automatic Date record was updated (in ISO8601 format)
companyId String Automatic Your company ID

Item Properties

Property Type Required Description
_id String Automatic ID of this record
type String Required What is the line item type (ie. product, tax, shipping)
title String Optional The title or description of the product
sku String Required The SKU of the item
quantity Number Required The amount ordered in units (or grams)
price Number Required The price, in the order currency, in 100s (ie. 9.99)
vendor String Optional The source supplier of the product

Fulfillment Properties

Property Type Required Description
_id String Automatic ID of this record
type String Required What is the fulfillment type (ie. shipment, return)
status String Required The status of the shipment (complete, pending, hold)
carrier String Optional The carrier responsible for the shipment
trackingNumbers Array Optional An array of tracking numbers (ie. ['123', '543'])
urls Array Optional An array of URLs
items Array Required An array of SKUs

Address Properties

Property Type Required Description
_id String Automatic ID of this record
type String Required What is the address type (ie. shipping, billing, HQ)
name String Required The full name of the addressee or care/of
company String Optional The company name of the addressee
phone String Optional The phone number attached to this address
city String Required The city associated with this addressee
zip String Required The zip or posal code
country String Required The country
addressOne String Required The address itself, including street and number
addressTwo String Optional Secondary address information (ie. PO box, unit)

Get Order by ID

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "parentCode": "54321",
  "posted": true,
  "shipped": true,
  "billed": true,
  "complete": true,
  "partner": "my-partner",
  "date": "2018-01-28 16:46:13",
  "items": [
    {
      "title": "Great Custom Product",
      "quantity": 2,
      "price": 9.99,
      "sku": "123GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [],
      "grams": 200
    }
  ],
  "fulfillments": [],
  "addresses": [
    {
      "type": "shipping",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    },
    {
      "type": "billing",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    }
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "companyId": "convictional-wholesale"
}

This endpoint returns a single order by ID.

Endpoint

https://api.convictional.com/orders/:id

Request example

GET https://api.convictional.com/orders/5a692f658f6d524e8282dac7

Get Orders by Query

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "code": "12345",
    "parentCode": "54321",
    "posted": true,
    "shipped": true,
    "billed": true,
    "complete": true,
    "partner": "convictional-dropshipper-us",
    "date": "2018-01-28 16:46:13",
    "items": [
      {
        "title": "Great Custom Product",
        "quantity": 2,
        "price": 9.99,
        "sku": "123GRPRODUCT",
        "vendor": "convictional-wholesale",
        "properties": [
          {
            "type": "custom_engraving",
            "data": "We Love Dad!"
          }
        ],
        "grams": 200
      },
      {
        "title": "Great Standard Product",
        "quantity": 1,
        "price": 19.99,
        "sku": "35GRPRODUCT",
        "vendor": "convictional-wholesale",
        "properties": [],
        "grams": 200
      }
    ],
    "fulfillments": [
      {
        "status": "complete",
        "carrier": "USPS",
        "trackingNumbers": [
          "123ABC", "DEF321"
        ],
        "urls": [
          "https://track.com/123ABC",
          "https://track.com/DEF321"
        ],
        "items": [{
          "sku": "123",
          "title": "Product",
          "quantity": 2
        }]
      }
    ],
    "addresses": [
      {
        "type": "shipping",
        "name": "First Last",
        "company": "Company, Inc",
        "phone": "800-555-5555",
        "city": "Toronto",
        "zip": "M5V 4B3",
        "state": "Ontario",
        "country": "Canada",
        "addressOne": "123 Toronto St.",
        "addressTwo": "#206"
      },
      {
        "type": "billing",
        "name": "First Last",
        "company": "Company, Inc",
        "phone": "800-555-5555",
        "city": "Toronto",
        "zip": "M5V 4B3",
        "state": "Ontario",
        "country": "Canada",
        "addressOne": "123 Toronto St.",
        "addressTwo": "#206"
      }
    ],
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "companyId": "convictional-wholesale"
  },
  {
    "_id": "5a692f658f6d524e8282dac8",
    "code": "12346",
    "parentCode": "54321",
    "posted": true,
    "shipped": true,
    "billed": true,
    "complete": true,
    "partner": "convictional-dropshipper-ca",
    "date": "2018-01-31 13:23:13",
    "items": [
      {
        "title": "Great Custom Product",
        "quantity": 2,
        "price": 9.99,
        "sku": "123GRPRODUCT",
        "vendor": "convictional-wholesale",
        "properties": [
          {
            "type": "custom_engraving",
            "data": "We Love Dad!"
          }
        ],
        "grams": 200
      },
      {
        "title": "Great Standard Product",
        "quantity": 1,
        "price": 19.99,
        "sku": "35GRPRODUCT",
        "vendor": "convictional-wholesale",
        "properties": [],
        "grams": 200
      }
    ],
    "fulfillments": [
      {
        "status": "complete",
        "carrier": "USPS",
        "trackingNumbers": [
          "123ABC", "DEF321"
        ],
        "urls": [
          "https://track.com/123ABC",
          "https://track.com/DEF321"
        ],
        "items": [{
          "sku": "123",
          "title": "Product",
          "quantity": 2
        }]
      }
    ],
    "addresses": [
      {
        "type": "shipping",
        "name": "First Last",
        "company": "Company, Inc",
        "phone": "800-555-5555",
        "city": "Toronto",
        "zip": "M5V 4B3",
        "state": "Ontario",
        "country": "Canada",
        "addressOne": "123 Toronto St.",
        "addressTwo": "#206"
      },
      {
        "type": "billing",
        "name": "First Last",
        "company": "Company, Inc",
        "phone": "800-555-5555",
        "city": "Toronto",
        "zip": "M5V 4B3",
        "state": "Ontario",
        "country": "Canada",
        "addressOne": "123 Toronto St.",
        "addressTwo": "#206"
      }
    ],
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "companyId": "convictional-wholesale"
  }
]

This endpoint returns all your orders.

Endpoint

https://api.convictional.com/orders

Open example

GET https://api.convictional.com/orders

Filtered example

GET https://api.convictional.com/orders?createdBefore=2018-02-28T11:26:43.000-0500

Query Parameters

Property Type Required Description
fields String Optional Return only the specified fields, comma separated
page Number Optional Return only records on a specific page
limit Number Optional Return up to this number of records
count Boolean Optional Return a count of documents, defaults to false
posted Boolean Optional Filter records by whether they are in your system
shipped Boolean Optional Filter records by whether they are shipped
billed Boolean Optional Filter records by whether they are billed
complete Boolean Optional Filter records by whether they are complete
partner String Optional Filter records by a particular partner
code String Optional Filter records by a particular order code
createdBefore Date Optional Filter records created before this date (ISO8601)
createdAfter Date Optional Filter records created after this date (ISO8601)
updatedBefore Date Optional Filter records updated before this date (ISO8601)
updatedAfter Date Optional Filter records updated after this date (ISO8601)
live Boolean Optional Filter by live mode status (true or false)

Create Order

Request Body (JSON):

{
  "code": "12345",
  "parentCode": "54321",
  "partner": "convictional-dropshipper-us",
  "date": "2018-01-28 16:46:13",
  "items": [
    {
      "title": "Great Custom Product",
      "quantity": 2,
      "price": 9.99,
      "sku": "123GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [],
      "grams": 200
    }
  ],
  "addresses": [
    {
      "type": "shipping",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    },
    {
      "type": "billing",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    }
  ]
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "parentCode": "54321",
  "posted": true,
  "shipped": true,
  "billed": true,
  "complete": true,
  "partner": "convictional-dropshipper-us",
  "date": "2018-01-28 16:46:13",
  "items": [
    {
      "title": "Great Custom Product",
      "quantity": 2,
      "price": 9.99,
      "sku": "123GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [],
      "grams": 200
    }
  ],
  "fulfillments": [
    {
      "status": "complete",
      "carrier": "USPS",
      "trackingNumbers": [
        "123ABC", "DEF321"
      ],
      "urls": [
        "https://track.com/123ABC",
        "https://track.com/DEF321"
      ],
      "items": [{
        "sku": "123",
        "title": "Product",
        "quantity": 2
      }]
    }
  ],
  "addresses": [
    {
      "type": "shipping",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    },
    {
      "type": "billing",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    }
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "companyId": "convictional-wholesale"
}

This endpoint creates a new order.

Endpoint

https://api.convictional.com/orders

Request example

POST https://api.convictional.com/orders

Update Order

Request Body (JSON):

{
  "complete": true
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "parentCode": "54321",
  "posted": true,
  "shipped": true,
  "billed": true,
  "complete": true,
  "partner": "convictional-dropshipper-us",
  "date": "2018-01-28 16:46:13",
  "items": [
    {
      "title": "Great Custom Product",
      "quantity": 2,
      "price": 9.99,
      "sku": "123GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "vendor": "convictional-wholesale",
      "properties": [],
      "grams": 200
    }
  ],
  "fulfillments": [
    {
      "status": "complete",
      "carrier": "USPS",
      "trackingNumbers": [
        "123ABC", "DEF321"
      ],
      "urls": [
        "https://track.com/123ABC",
        "https://track.com/DEF321"
      ],
      "items": [{
        "sku": "123",
        "title": "Product",
        "quantity": 2
      }]
    }
  ],
  "addresses": [
    {
      "type": "shipping",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    },
    {
      "type": "billing",
      "name": "First Last",
      "company": "Company, Inc",
      "phone": "800-555-5555",
      "city": "Toronto",
      "zip": "M5V 4B3",
      "state": "Ontario",
      "country": "Canada",
      "addressOne": "123 Toronto St.",
      "addressTwo": "#206"
    }
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "companyId": "convictional-wholesale"
}

This endpoint updates a single order by ID.

Endpoint

https://api.convictional.com/orders/:id

Request example

PUT https://api.convictional.com/orders/5a692f658f6d524e8282dac7

Bulk Update/Create

Request Body (JSON):

{
  "orders": [
    {
      "code": "12345",
      "parentCode": "54321",
      "posted": true,
      "shipped": true,
      "billed": true,
      "complete": true,
      "partner": "convictional-dropshipper-us",
      "date": "2018-01-28 16:46:13",
      "items": [
        {
          "title": "Great Custom Product",
          "quantity": 2,
          "price": 9.99,
          "sku": "123GRPRODUCT",
          "vendor": "convictional-wholesale",
          "properties": [
            {
              "type": "custom_engraving",
              "data": "We Love Dad!"
            }
          ],
          "grams": 200
        },
        {
          "title": "Great Standard Product",
          "quantity": 1,
          "price": 19.99,
          "sku": "35GRPRODUCT",
          "vendor": "convictional-wholesale",
          "properties": [],
          "grams": 200
        }
      ],
      "addresses": [
        {
          "type": "shipping",
          "name": "First Last",
          "company": "Company, Inc",
          "phone": "800-555-5555",
          "city": "Toronto",
          "zip": "M5V 4B3",
          "state": "Ontario",
          "country": "Canada",
          "addressOne": "123 Toronto St.",
          "addressTwo": "#206"
        },
        {
          "type": "billing",
          "name": "First Last",
          "company": "Company, Inc",
          "phone": "800-555-5555",
          "city": "Toronto",
          "zip": "M5V 4B3",
          "state": "Ontario",
          "country": "Canada",
          "addressOne": "123 Toronto St.",
          "addressTwo": "#206"
        }
      ]
    },
    {
      "code": "12346",
      "parentCode": "54321",
      "posted": true,
      "shipped": true,
      "billed": true,
      "complete": true,
      "partner": "convictional-dropshipper-ca",
      "date": "2018-01-31 13:23:13",
      "items": [
        {
          "title": "Great Custom Product",
          "quantity": 2,
          "price": 9.99,
          "sku": "123GRPRODUCT",
          "vendor": "convictional-wholesale",
          "properties": [
            {
              "type": "custom_engraving",
              "data": "We Love Dad!"
            }
          ],
          "grams": 200
        },
        {
          "title": "Great Standard Product",
          "quantity": 1,
          "price": 19.99,
          "sku": "35GRPRODUCT",
          "vendor": "convictional-wholesale",
          "properties": [],
          "grams": 200
        }
      ],
      "addresses": [
        {
          "type": "shipping",
          "name": "First Last",
          "company": "Company, Inc",
          "phone": "800-555-5555",
          "city": "Toronto",
          "zip": "M5V 4B3",
          "state": "Ontario",
          "country": "Canada",
          "addressOne": "123 Toronto St.",
          "addressTwo": "#206"
        },
        {
          "type": "billing",
          "name": "First Last",
          "company": "Company, Inc",
          "phone": "800-555-5555",
          "city": "Toronto",
          "zip": "M5V 4B3",
          "state": "Ontario",
          "country": "Canada",
          "addressOne": "123 Toronto St.",
          "addressTwo": "#206"
        }
      ]
    }
  ]
}

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) orders. If the code matches an existing record, it will update. Otherwise, it will create.

Endpoint

https://api.convictional.com/orders

Request example

PUT https://api.convictional.com/orders

Delete Order

Returns (JSON):

{
  "Deleted": 1
}

This endpoint deletes a single order by ID.

Endpoint

https://api.convictional.com/orders/:id

Request example

DELETE https://api.convictional.com/orders/5a692f658f6d524e8282dac7

Products

REST endpoints that allow you to create, retrieve, update and delete products.

Product Properties

Property Type Required Description
_id String Automatic ID of this record
code String Required The product code in your system
title String Required The name of the product
active Boolean Required Is this product active?
bodyHtml String Optional HTML for consumer-facing pages
options Array Optional Contains product options
images Array Optional Contains image source URLs and priority
tags Array Optional Contains tags ie. ['summer', 'beauty']
type String Required 'item', 'shipping', 'tax' or 'custom'
variants Array Required All the variations of the product
vendor String Optional The brand of the product
custom Array Optional Custom key/value pairs
live Boolean Automatic True for live mode, false for test mode
created Date Automatic Date record was created (in ISO8601 format)
updated Date Automatic Date record was updated (in ISO8601 format)
companyId String Automatic Your company ID

Options Properties

Property Type Required Description
_id String Automatic ID of this record
name String Required The name of the product option (ie. size)
type String Optional The type of the option (ie. text, select)
position String Optional The priority order of the option (lower = higher priority)

Variants Properties

Property Type Required Description
_id String Automatic ID of this record
id String Required The variant code in your system
title String Required A description of the variant (ie. Black, XL)
sku String Required The unique for this SKU (affects pricing)
inventory_quantity String Required The amount you have available to ship

Images Properties

Property Type Required Description
_id String Automatic ID of this record
src String Required The URL where the image is hosted
position String Optional The priority (0-n, 0 is highest priority)

Get Product by ID

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "active": true,
  "bodyHtml": "<p>Great product!</p>",
  "images": [
    { 
      "src": "https://cdn.convictional.com/a",
      "position": 0
    },
    {
      "src": "https://cdn.convictional.com/b",
      "position": 0  
    },
  ],
  "tags": ["Toronto", "Beauty", "Mens"],
  "title": "Great product",
  "type": "item",
  "variants": [
    { 
      "sku": "123", 
      "title": "Great variant", 
      "inventory_quantity": "8", 
      "price": 9.99 
    },
    { 
      "sku": "321", 
      "title": "Great variant", 
      "inventory_quantity": "3", 
      "price": 19.99 
    }
  ],
  "vendor": "Convictional Wholesale",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint returns a single product by ID.

Endpoint

https://api.convictional.com/products/:id

Request example

GET https://api.convictional.com/products/5a692f658f6d524e8282dac7

Get Products by Query

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "code": "12345",
    "active": true,
    "bodyHtml": "<p>Great product!</p>",
    "images": [
      { "src": "https://cdn.convictional.com/123abc" },
      { "src": "https://cdn.convictional.com/987zyx" },
    ],
    "tags": ["Toronto", "Beauty", "Mens"],
    "title": "Great product",
    "type": "item",
    "variants": [
      { 
        "sku": "123", 
        "title": "Great variant", 
        "inventory_quantity": "8", 
        "price": 9.99 
      },
      { 
        "sku": "321", 
        "title": "Great variant", 
        "inventory_quantity": "3", 
        "price": 19.99 
      }
    ],
    "vendor": "Convictional Wholesale",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  },
  {
    "_id": "5a692f658f6d524e8282dac8",
    "code": "12346",
    "active": true,
    "bodyHtml": "<p>Greatest product!</p>",
    "images": [
      { "src": "https://cdn.convictional.com/456bec" },
      { "src": "https://cdn.convictional.com/111qwe" },
    ],
    "tags": ["Waterloo", "Fashion", "Womens"],
    "title": "Greatest product",
    "type": "item",
    "variants": [
      { 
        "sku": "456", 
        "title": "Great variant", 
        "inventory_quantity": "12", 
        "price": 29.99 
      },
      { 
        "sku": "789", 
        "title": "Great variant", 
        "inventory_quantity": "6", 
        "price": 39.99 
      }
    ],
    "vendor": "Convictional Wholesale",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  }
]

This endpoint returns all your products.

Endpoint

https://api.convictional.com/products

Open example

GET https://api.convictional.com/products

Filtered example

GET https://api.convictional.com/products?createdBefore=2018-02-28T11:26:43.000-0500

Query Parameters

Property Type Required Description
active Boolean Optional Filter by active status (true or false)
fields String Optional Return only the specified fields, comma separated
page Number Optional Return only records on a specific page
limit Number Optional Return up to this number of records
count Boolean Optional Return a count of documents, defaults to false
createdBefore Date Optional Filter records created before this date (ISO8601)
createdAfter Date Optional Filter records created after this date (ISO8601)
updatedBefore Date Optional Filter records updated before this date (ISO8601)
updatedAfter Date Optional Filter records updated after this date (ISO8601)
live Boolean Optional Filter by live mode status (true or false)

Create Product

Request Body (JSON):

{
  "code": "12345",
  "active": true,
  "bodyHtml": "<p>Great product!</p>",
  "images": [
    { "src": "https://cdn.convictional.com/123abc" },
    { "src": "https://cdn.convictional.com/987zyx" },
  ],
  "tags": ["Toronto", "Beauty", "Mens"],
  "title": "Great product",
  "type": "item",
  "variants": [
    { 
      "sku": "123", 
      "title": "Great variant", 
      "inventory_quantity": "8", 
      "price": 9.99 
    },
    { 
      "sku": "321", 
      "title": "Great variant", 
      "inventory_quantity": "3", 
      "price": 19.99 
    }
  ],
  "live": true,
  "vendor": "Convictional Wholesale"
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "active": true,
  "bodyHtml": "<p>Great product!</p>",
  "images": [
    { "src": "https://cdn.convictional.com/123abc" },
    { "src": "https://cdn.convictional.com/987zyx" },
  ],
  "tags": ["Toronto", "Beauty", "Mens"],
  "title": "Great product",
  "type": "item",
  "variants": [
    { 
      "sku": "123", 
      "title": "Great variant", 
      "inventory_quantity": "8", 
      "price": 9.99 
    },
    { 
      "sku": "321", 
      "title": "Great variant", 
      "inventory_quantity": "3", 
      "price": 19.99 
    }
  ],
  "vendor": "Convictional Wholesale",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint creates a new product.

Endpoint

https://api.convictional.com/products

Request example

POST https://api.convictional.com/products

Update Product

Request Body (JSON):

{
  "active": false,
  "bodyHtml": "<p>Greater product!</p>",
  "title": "Greater product"
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "active": false,
  "bodyHtml": "<p>Greater product!</p>",
  "images": [
    { "src": "https://cdn.convictional.com/123abc" },
    { "src": "https://cdn.convictional.com/987zyx" },
  ],
  "tags": ["Toronto", "Beauty", "Mens"],
  "title": "Greater product",
  "type": "item",
  "variants": [
    { 
      "sku": "123", 
      "title": "Great variant", 
      "inventory_quantity": "8", 
      "price": 9.99 
    },
    { 
      "sku": "321", 
      "title": "Great variant", 
      "inventory_quantity": "3", 
      "price": 19.99 
    }
  ],
  "vendor": "Convictional Wholesale",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint updates a single product by ID.

Endpoint

https://api.convictional.com/products/:id

Request example

PUT https://api.convictional.com/products/5a692f658f6d524e8282dac7

Bulk Update/Create

Request Body (JSON):

{
  "products": [
    {
      "code": "12345",
      "active": true,
      "bodyHtml": "<p>Great product!</p>",
      "images": [
        { "src": "https://cdn.convictional.com/123abc" },
        { "src": "https://cdn.convictional.com/987zyx" },
      ],
      "tags": ["Toronto", "Beauty", "Mens"],
      "title": "Great product",
      "type": "item",
      "variants": [
        { 
          "sku": "123", 
          "title": "Great variant", 
          "inventory_quantity": "8", 
          "price": 9.99 
        },
        { 
          "sku": "321", 
          "title": "Great variant", 
          "inventory_quantity": "3", 
          "price": 19.99 
        }
      ],
      "vendor": "Convictional Wholesale",
      "live": true
    },
    {
      "code": "12346",
      "active": true,
      "bodyHtml": "<p>Greatest product!</p>",
      "images": [
        { "src": "https://cdn.convictional.com/456bec" },
        { "src": "https://cdn.convictional.com/111qwe" },
      ],
      "tags": ["Waterloo", "Fashion", "Womens"],
      "title": "Greatest product",
      "type": "item",
      "variants": [
        { 
          "sku": "456", 
          "title": "Great variant", 
          "inventory_quantity": "12", 
          "price": 29.99 
        },
        { 
          "sku": "789", 
          "title": "Great variant", 
          "inventory_quantity": "6", 
          "price": 39.99 
        }
      ],
      "vendor": "Convictional Wholesale",
      "live": true
    }
  ]
}

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) products. If the code matches an existing record, it will update. Otherwise, it will create.

Endpoint

https://api.convictional.com/products

Request example

PUT https://api.convictional.com/products

Delete Product

Returns (String):

{
  "Deleted": 1
}

This endpoint deletes a single product by ID.

Endpoint

https://api.convictional.com/products/:id

Request example

DELETE https://api.convictional.com/products/5a692f658f6d524e8282dac7

Partners

REST endpoints that allow you to create, retrieve, update and delete partners.

Partner Properties

Property Type Required Description
_id String Automatic ID of this record
email String Required The business email for this partner
active Boolean Required Do you want to sync with them?
invited Boolean Automatic Have they been invited?
force Boolean Optional Overwrite products? Excludes prices/inventory.
billing Boolean Optional Do you want to bill them here?
priceList String Optional The name of their price list
relationship String Required Relative to you: 'parent', 'child' or 'self'
itemLookup Array Optional A reference of your item codes and theirs
custom Array Optional Custom key/value pairs
live Boolean Automatic True for live mode, false for test mode
created Date Automatic Date record was created (in ISO8601 format)
updated Date Automatic Date record was updated (in ISO8601 format)
companyId String Automatic Your company ID

Get Partner by ID

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "email": "capartner@example.com",
  "active": true,
  "force": true,
  "invited": true,
  "billing": true,
  "itemLookup": [
    {
      "myId": "12345",
      "yourId": "ABC123"
    },
    {
      "myId": "56789",
      "yourId": "XYZ098"
    }
  ],
  "priceList": "Price List for Canada",
  "relationship": "child",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint returns a single partner by ID.

Endpoint

https://api.convictional.com/partners/:id

Request example

GET https://api.convictional.com/partners/5a692f658f6d524e8282dac7

Get Partners by Query

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "email": "capartner@example.com",
    "active": true,
    "force": true,
    "invited": true,
    "billing": true,
    "itemLookup": [
      {
        "myId": "12345",
        "yourId": "ABC123"
      },
      {
        "myId": "56789",
        "yourId": "XYZ098"
      }
    ],
    "priceList": "Price List for Canada",
    "relationship": "child",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  },
  {
    "_id": "5a692f658f6d524e8282dac7",
    "email": "uspartner@example.com",
    "active": true,
    "force": true,
    "invited": true,
    "billing": true,
    "itemLookup": [
      {
        "myId": "12345",
        "yourId": "ABC123"
      },
      {
        "myId": "56789",
        "yourId": "XYZ098"
      }
    ],
    "priceList": "Price List for USA",
    "relationship": "child",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  }
]

This endpoint returns all your partners.

Endpoint

https://api.convictional.com/partners

Open example

GET https://api.convictional.com/partners

Filtered example

GET https://api.convictional.com/partners?createdBefore=2018-02-28T11:26:43.000-0500

Query Parameters

Property Type Required Description
fields String Optional Return only the specified fields, comma separated
page Number Optional Return only records on a specific page
limit Number Optional Return up to this number of records
count Boolean Optional Return a count of documents, defaults to false
active Boolean Optional Filter by active status (true or false)
invited Boolean Optional Filter by invited status (true or false)
force Boolean Optional Filter by whether to force overwrite products
relationship String Optional Filter by relationship (child, self or parent)
createdBefore Date Optional Filter records created before this date (ISO8601)
createdAfter Date Optional Filter records created after this date (ISO8601)
updatedBefore Date Optional Filter records updated before this date (ISO8601)
updatedAfter Date Optional Filter records updated after this date (ISO8601)
live Boolean Optional Filter by live mode status (true or false)

Create Partner

Request Body (JSON):

{
  "email": "capartner@example.com",
  "priceList": "Price List for Canada",
  "relationship": "child"
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
    "email": "capartner@example.com",
    "active": true,
    "force": true,
    "invited": true,
    "billing": true,
  "itemLookup": [
    {
      "myId": "12345",
      "yourId": "ABC123"
    },
    {
      "myId": "56789",
      "yourId": "XYZ098"
    }
  ],
  "priceList": "Price List for Canada",
  "relationship": "child",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint creates a new partner.

Endpoint

https://api.convictional.com/partners

Request example

POST https://api.convictional.com/partners

Update Partner

Request Body (JSON):

{
  "active": false
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "email": "capartner@example.com",
  "active": true,
  "force": true,
  "invited": true,
  "billing": true,
  "itemLookup": [
    {
      "myId": "12345",
      "yourId": "ABC123"
    },
    {
      "myId": "56789",
      "yourId": "XYZ098"
    }
  ],
  "priceList": "Price List for Canada",
  "relationship": "child",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint updates a single partner by ID.

Endpoint

https://api.convictional.com/partners/:id

Request example

PUT https://api.convictional.com/partners/5a692f658f6d524e8282dac7

Bulk Update/Create

Request Body (JSON):

{
  "partners": [
    {
      "email": "capartner@example.com",
      "priceList": "Price List for Canada",
      "relationship": "child",
    },
    {
      "email": "uspartner@example.com",
      "priceList": "Price List for USA",
      "relationship": "child",
    }
  ]
}

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) partners. If the email matches an existing record, it will update. Otherwise, it will create. Maximum is 100 records, above that please send multiple requests to this endpoint.

Endpoint

https://api.convictional.com/partners

Request example

PUT https://api.convictional.com/partners

Delete Partner

Returns (JSON):

{
  "Deleted": 1
}

This endpoint deletes a single partner by ID.

Endpoint

https://api.convictional.com/partners/:id

Request example

DELETE https://api.convictional.com/partners/5a692f658f6d524e8282dac7

Prices

REST endpoints that allow you to create, retrieve, update and delete prices.

Price Properties

Property Type Required Description
_id String Automatic ID of this record
listName String Required Name of this price list
startDate String Optional Start date (in RFC3339 format)
endDate String Optional End date (in RFC3339 format)
currencyName String Optional Currency code (in ISO4217 format)
conversion Number Optional Conversion rate from base (default "1")
markup Number Optional Markup percentage (default "100")
rounding String Optional Decimals on the prices ("00" is $10.00)
list Array Required An array containing list items
custom Array Optional Custom key/value pairs
live Boolean Automatic True for live mode, false for test mode
created Date Automatic Date record was created (in ISO8601 format)
updated Date Automatic Date record was updated (in ISO8601 format)
companyId String Automatic Your company ID

List Item Properties

Property Type Required Description
_id String Automatic ID of this record
sku String Required The SKU of the variant to price
price Number Required The base (wholesale) price of the item
markup Number Required The markup, to arrive at retail price
type String Required The markup type ('fixed' or 'percent')

Get Price by ID

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "listName": "Price List for USA",
  "startDate": "2018/01/01",
  "endDate": "2018/01/31",
  "currencyName": "USD",
  "conversion": 1.2,
  "markup": 120,
  "rounding": "99",
  "list": [
    {
      "sku": "123",
      "price": 9.99,
      "markup": 10,
      "type": "fixed"
    },
    {
      "sku": "321",
      "price": 19.99,
      "markup": 120,
      "type": "percent" },
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint returns a single price by ID.

Endpoint

https://api.convictional.com/prices/:id

Request example

GET https://api.convictional.com/prices/5a692f658f6d524e8282dac7

Get Prices by Query

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "listName": "Price List for USA",
    "startDate": "2018/01/01",
    "endDate": "2018/01/31",
    "currencyName": "USD",
    "conversion": 1.2,
    "markup": 120,
    "rounding": "99",
    "list": [
      {
        "sku": "123",
        "price": 9.99,
        "markup": 10,
        "type": "fixed"
      },
      {
        "sku": "321",
        "price": 19.99,
        "markup": 120,
        "type": "percent"
      }
    ],
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  },
  {
    "_id": "5a692f658f6d524e8282dac8",
    "listName": "Price List for Canada",
    "startDate": "2018/01/01",
    "endDate": "2018/01/31",
    "currencyName": "CAD",
    "conversion": 1,
    "markup": 100,
    "rounding": "99",
    "list": [
      {
        "sku": "456",
        "price": 9.99,
        "markup": 10,
        "type": "fixed"
      },
      {
        "sku": "678",
        "price": 19.99,
        "markup": 120,
        "type": "percent"
      },
    ],
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "live": true,
    "companyId": "convictional-wholesale"
  }
]

This endpoint returns all your prices.

Endpoint

https://api.convictional.com/prices

Open example

GET https://api.convictional.com/prices

Filtered example

GET https://api.convictional.com/prices?createdBefore=2018-02-28T11:26:43.000-0500

Query Parameters

Property Type Required Description
fields String Optional Return only the specified fields, comma separated
page Number Optional Return only records on a specific page
limit Number Optional Return up to this number of records
count Boolean Optional Return a count of documents, defaults to false
listName String Optional Filter by name. Returns any list containing string
createdBefore Date Optional Filter records created before this date (ISO8601)
createdAfter Date Optional Filter records created after this date (ISO8601)
updatedBefore Date Optional Filter records updated before this date (ISO8601)
updatedAfter Date Optional Filter records updated after this date (ISO8601)
live Boolean Optional Filter by live mode status (true or false)

Create Price

Request Body (JSON):

{
  "listName": "Price List for Canada",
  "startDate": "2018/01/01",
  "endDate": "2018/01/31",
  "currencyName": "CAD",
  "conversion": 1,
  "markup": 100,
  "rounding": "99",
  "list": [
    {
      "sku": "123",
      "price": 9.99,
      "markup": 10,
      "type": "fixed"
    },
    {
      "sku": "321",
      "price": 19.99,
      "markup": 120,
      "type": "percent"
    },
  ],
  "live": true
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac8",
  "listName": "Price List for Canada",
  "startDate": "2018/01/01",
  "endDate": "2018/01/31",
  "currencyName": "CAD",
  "conversion": 1,
  "markup": 100,
  "rounding": "99",
  "list": [
    {
      "sku": "123",
      "price": 9.99,
      "markup": 10,
      "type": "fixed"
    },
    {
      "sku": "321",
      "price": 19.99,
      "markup": 120,
      "type": "percent"
    },
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint creates a new price.

Endpoint

https://api.convictional.com/prices

Request example

POST https://api.convictional.com/prices

Update Price

Request Body (JSON):

{
  "markup": 110,
  "rounding": "00",
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac8",
  "listName": "Price List for Canada",
  "startDate": "2018/01/01",
  "endDate": "2018/01/31",
  "currencyName": "CAD",
  "conversion": 1,
  "markup": 110,
  "rounding": "00",
  "list": [
    {
      "sku": "123",
      "price": 9.99,
      "markup": 10,
      "type": "fixed"
    },
    {
      "sku": "321",
      "price": 19.99,
      "markup": 120,
      "type": "percent"
    },
  ],
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint updates a single price by ID.

Endpoint

https://api.convictional.com/prices/:id

Request example

PUT https://api.convictional.com/prices/5a692f658f6d524e8282dac8

Bulk Update/Create

Request Body (JSON):

{
  "prices": [
    {
      "listName": "Price List for USA",
      "startDate": "2018/01/01",
      "endDate": "2018/01/31",
      "currencyName": "USD",
      "conversion": 1.2,
      "markup": 120,
      "rounding": "99",
      "list": [
        {
          "sku": "123",
          "price": 9.99,
          "markup": 10,
          "type": "fixed"
        },
        {
          "sku": "321",
          "price": 19.99,
          "markup": 120,
          "type": "percent"
        },
      ],
      "live": true
    },
    {
      "listName": "Price List for Canada",
      "startDate": "2018/01/01",
      "endDate": "2018/01/31",
      "currencyName": "CAD",
      "conversion": 1,
      "markup": 100,
      "rounding": "99",
      "list": [
        {
          "sku": "456",
          "price": 9.99,
          "markup": 10,
          "type": "fixed"
        },
        {
          "sku": "678",
          "price": 19.99,
          "markup": 120,
          "type": "percent"
        },
      ],
      "live": true
    }
  ]
}

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) prices. If the list name matches an existing record, it will update. Otherwise, it will create.

Endpoint

https://api.convictional.com/prices

Request example

PUT https://api.convictional.com/prices

Delete Price

Returns (JSON):

{
  "Deleted": 1
}

This endpoint deletes a single price by ID.

Endpoint

https://api.convictional.com/prices/:id

Request example

DELETE https://api.convictional.com/prices/5a692f658f6d524e8282dac7

Logs

REST endpoints that allow you to create, retrieve, update and delete logs.

Log Properties

Property Type Required Description
_id String Automatic ID of this record
description String Required A description of what you are logging
custom Array Optional Custom key/value pairs
live Boolean Automatic True for live mode, false for test mode
created Date Automatic Date record was created (in ISO8601 format)
updated Date Automatic Date record was updated (in ISO8601 format)
companyId String Automatic Your company ID

Get Log by ID

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "description": "Welcome to Convictional",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "companyId": "convictional-wholesale"
}

This endpoint returns a single log by ID.

Endpoint

https://api.convictional.com/logs/:id

Request example

GET https://api.convictional.com/logs/5a692f658f6d524e8282dac7

Get Logs by Query

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "description": "Welcome to Convictional",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "custom": [
      {
        "key": "statusCode",
        "type": "number",
        "value": 200
      },
      {
        "key": "path",
        "type": "string",
        "value": "/orders"
      }
    ],
    "live": true,
    "companyId": "convictional-wholesale"
  },
  {
    "_id": "5a692f658f6d524e8282dac8",
    "description": "Successful request",
    "created": "2018-02-12T15:14:27.147-0500",
    "updated": "2018-02-12T15:14:27.147-0500",
    "custom": [
      {
        "key": "statusCode",
        "type": "number",
        "value": 200
      },
      {
        "key": "path",
        "type": "string",
        "value": "/orders"
      }
    ],
    "live": true,
    "companyId": "convictional-wholesale"
  }
]

This endpoint returns all your logs.

Get

https://api.convictional.com/logs

Open example

GET https://api.convictional.com/logs

Filtered example

GET https://api.convictional.com/logs?createdBefore=2018-02-28T11:26:43.000-0500

Query Parameters

Property Type Required Description
fields String Optional Return only the specified fields, comma separated
page Number Optional Return only records on a specific page
limit Number Optional Return up to this number of records
count Boolean Optional Return a count of documents, defaults to false
createdBefore Date Optional Filter records created before this date (ISO8601)
createdAfter Date Optional Filter records created after this date (ISO8601)
updatedBefore Date Optional Filter records updated before this date (ISO8601)
updatedAfter Date Optional Filter records updated after this date (ISO8601)
live Boolean Optional Filter by live mode status (true or false)

Create Log

Request Body (JSON):

{
  "description": "Welcome to Convictional",
  "custom": [
      {
        "key": "statusCode",
        "type": "number",
        "value": 200
      },
      {
        "key": "path",
        "type": "string",
        "value": "/orders"
      }
    ],
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "description": "Welcome to Convictional",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "custom": [
    {
      "key": "statusCode",
      "type": "number",
      "value": 200
    },
    {
      "key": "path",
      "type": "string",
      "value": "/orders"
    }
  ],
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint creates a new log.

Endpoint

https://api.convictional.com/logs

Request example

POST https://api.convictional.com/logs

Update Log

Request Body (JSON):

{
  "description": "Welcome to Convictional!"
}

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "description": "Welcome to Convictional!",
  "created": "2018-02-12T15:14:27.147-0500",
  "updated": "2018-02-12T15:14:27.147-0500",
  "custom": [
    {
      "key": "statusCode",
      "type": "number",
      "value": 200
     },
    {
      "key": "path",
      "type": "string",
      "value": "/orders"
    }
  ],
  "live": true,
  "companyId": "convictional-wholesale"
}

This endpoint updates a single log by ID.

Endpoint

https://api.convictional.com/logs/:id

Request example

PUT https://api.convictional.com/logs/5a692f658f6d524e8282dac7

Bulk Update/Create

Request Body (JSON):

{
  "logs": [
    {
      "_id": "5a692f658f6d524e8282dac7",
      "description": "Welcome to Convictional"
    },
    {
      "_id": "5a692f658f6d524e8282dac7",
      "description": "This is a new description"
    }
  ]
}

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) logs. If the ID matches an existing record, it will update. Otherwise, it will create.

Endpoint

https://api.convictional.com/logs

Request example

PUT https://api.convictional.com/logs

Delete Log

Returns (JSON):

{
  "Deleted": 1
}

This endpoint deletes a single log by ID.

Endpoint

https://api.convictional.com/logs/:id

Request example

DELETE https://api.convictional.com/logs/5a692f658f6d524e8282dac7

Changelog

1.6.0 - 2018-06-12

1.5.6 - 2018-06-04

1.5.5 - 2018-05-31

1.5.4 - 2018-05-26

1.5.3 - 2018-05-23

1.5.2 - 2018-05-23

1.4.8 - 2018-05-04

1.4.7 - 2018-05-02

1.1.7 - 2018-04-02

1.1.6 - 2018-03-28

1.1.5 - 2018-03-23

1.1.4 - 2018-03-18

1.1.3 - 2018-03-14

1.1.2 - 2018-03-13

1.1.1 - 2018-03-13

1.1.0 - 2018-03-12

1.0.9 - 2018-03-08

1.0.8 - 2018-03-08

1.0.7 - 2018-03-08

1.0.6 - 2018-03-08

1.0.5 - 2018-03-08

1.0.4 - 2018-03-06

1.0.3 - 2018-03-05

1.0.2 - 2018-03-05

1.0.10 - 2018-03-05