Tap for Menu

Introduction

API Endpoint:

https://api.convictional.com

Welcome to the Convictional API documentation. You can use our API to access various resources on the Convictional platform. We use this API and this documentation every day to build our own applications, so we build it to be as easy to use and scalable as we can.

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. Almost anything you can do in the admin, you can do here too. Let us know what you think.

Versioning

Last Updated:

{ "2018-05-02" }

When breaking changes happen in the future, we will notify users and migrate you to the new version.

Authentication

Request Headers:

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

Convictional uses API keys to authenticate your requests. When you register your account, we generate an API 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.

Bulk Endpoints

Request Body (JSON):

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

Convictional offers bulk endpoints. This allows you to create, read, update and delete up to 100 records as once. You can go above 100 records at a time but your request may be rejected on the basis of size. The max data size is 6mb. If you use our client library we handle the queuing and chunking for you. Send an array of records instead of a single record to create, update and delete endpoints to use bulk abilities.

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) => {
  console.log(order) // Do stuff with record...
}).catch((error) => { console.error(error) })

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

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:

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

Example:

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

Convictional allows use of custom key/value pairs on all records. Over time we will migrate some of our more user-specific fields over to use this format, so you can define your own data.

The three types we currently support are: strings, numbers and 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.

Actions

RPC endpoints that allow you to translate EDI documents, invite partners and more

Sync

Returns JSON:

{
  "Successfully pushed getOrders to queue"
}

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

Endpoint URL

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

HTTP Request example

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

Sync Methods

Method Description
getOrders Trigger an event that will get the orders from all your trading partners
getOrderUpdates Trigger an event that will get order updates from your system
postOrders Trigger an event that will push orders from Convictional into your system
postOrderUpdates Trigger an event that will push order updates to all your trading partners
getProducts Trigger an event that will get products from your system
postProducts Trigger an event that will push products to your trading partners
getProductUpdates Trigger an event that will get inventory from your system
postProductUpdates Trigger an event that will push inventory to your trading partners

Translate

Returns JSON structured like this:

{
  "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.

Endpoint URL

https://api.convictional.com/translate

HTTP Request 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)

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 Order number in the source ecommerce system
parentCode String Required Parent prder number in the system of record
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 Is this order shipped and billed?
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 the tracking information
addresses Array Optional Contains all the customer addresses
returns Array Optional Contains all the returns for this order
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 Order

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"
    }
  ],
  "returns": [],
  "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 (bulk)

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"
      }
    ],
    "returns": [],
    "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"
      }
    ],
    "returns": [],
    "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)

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"
    }
  ],
  "returns": [],
  "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

Create Orders (bulk)

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

{
  "0": "5a8755c66affcc608657ed2c",
  "1": "5a8755c66affcc608657ed2d"
}

This endpoint creates multiple new orders. Occurs automatically when you pass an array of order objects to this endpoint.

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"
    }
  ],
  "returns": [],
  "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

Update Orders (bulk)

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

Delete Orders (bulk)

Request Body (JSON):

[
  "5a8755c66affcc608657ed2c",
  "5a8755c66affcc608657ed2d"
]

Returns (JSON):

{
  "Deleted": 2
}

This endpoint deletes multiple orders by ID.

Endpoint

https://api.convictional.com/orders

Request example

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

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 consuming-facing pages
images Array Optional Contains image source URLs
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

Get Product

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 returns a single product by ID.

Endpoint

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

Request example

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

Get Products (bulk)

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

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

Create Products (bulk)

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 
        }
      ],
      "live": true,
      "vendor": "Convictional Wholesale",
    },
    {
      "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 
        }
      ],
      "live": true,
      "vendor": "Convictional Wholesale",
    }
  ]
}

Returns (JSON):

{
  "0": "5a8755c66affcc608657ed2c",
  "1": "5a8755c66affcc608657ed2d"
}

This endpoint creates multiple new products. Occurs automatically when you pass an array of product objects to this endpoint.

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

Update Products (bulk)

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

Delete Products (bulk)

Request Body (JSON):

[
  "5a8755c66affcc608657ed2c",
  "5a8755c66affcc608657ed2d"
]

Returns (JSON):

{
  "Deleted": 2
}

This endpoint deletes multiple products by ID.

Endpoint

https://api.convictional.com/products

Request example

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

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
code String Required The partner code in your system
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.
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

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "active": true,
  "force": true,
  "email": "capartner@example.com",
  "invited": 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 (bulk)

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "code": "12345",
    "active": true,
    "force": true,
    "email": "capartner@example.com",
    "invited": 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",
    "code": "12346",
    "active": false,
    "force": false,
    "email": "uspartner@example.com",
    "invited": 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)

Create Partner

Request Body (JSON):

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

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "active": true,
  "force": true,
  "email": "capartner@example.com",
  "invited": 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

Create Partners (bulk)

Request Body (JSON):

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

Returns (JSON):

{
  "0": "5a8755c66affcc608657ed2c",
  "1": "5a8755c66affcc608657ed2d"
}

This endpoint creates multiple new partners. Occurs automatically when you pass an array of partner objects to this endpoint. Maximum is 100 records, above that please send multiple requests to this endpoint.

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",
  "code": "12345",
  "active": false,
  "force": true,
  "email": "capartner@example.com",
  "invited": 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

Update Partners (bulk)

Request Body (JSON):

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

Returns (JSON):

{
  "Modified": 2
}

This endpoint updates (or creates) partners. If the code 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

Delete Partners (bulk)

Request Body (JSON):

[
  "5a8755c66affcc608657ed2c",
  "5a8755c66affcc608657ed2d"
]

Returns (JSON):

{
  "Deleted": 2
}

This endpoint deletes multiple partners by ID.

Endpoint

https://api.convictional.com/partners

Request example

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

Invite Partner

Request (JSON):

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

Returns (JSON):

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

This endpoint invites a single partner by email.

Endpoint

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

Request example

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

Message example


Subject: 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

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
code String Required Code in your system
listName String Required Name of this price list
startDate String Optional Start date (in ISO8601 format)
endDate String Optional End date (in ISO8601 format)
currencyName String Optional Name of the currency
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 sku, base price, markup, markup type
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 Price

Returns (JSON):

{
  "_id": "5a692f658f6d524e8282dac7",
  "code": "12345",
  "listName": "Price List for USA",
  "startDate": "2018/01/01 00:00:00",
  "endDate": "2018/01/31 23:59:59",
  "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 (bulk)

Returns (JSON):

[
  {
    "_id": "5a692f658f6d524e8282dac7",
    "code": "12345",
    "listName": "Price List for USA",
    "startDate": "2018/01/01 00:00:00",
    "endDate": "2018/01/31 23:59:59",
    "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",
    "code": "12346",
    "listName": "Price List for Canada",
    "startDate": "2018/01/01 00:00:00",
    "endDate": "2018/01/31 23:59:59",
    "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)

Create Price

Request Body (JSON):

{
  "code": "12346",
  "listName": "Price List for Canada",
  "startDate": "2018/01/01 00:00:00",
  "endDate": "2018/01/31 23:59:59",
  "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",
  "code": "12346",
  "listName": "Price List for Canada",
  "startDate": "2018/01/01 00:00:00",
  "endDate": "2018/01/31 23:59:59",
  "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

Create Prices (bulk)

Request Body (JSON):

{
  "prices": [
    {
      "code": "12345",
      "listName": "Price List for USA",
      "startDate": "2018/01/01 00:00:00",
      "endDate": "2018/01/31 23:59:59",
      "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
    },
    {
      "code": "12346",
      "listName": "Price List for Canada",
      "startDate": "2018/01/01 00:00:00",
      "endDate": "2018/01/31 23:59:59",
      "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):

{
  "0": "5a8755c66affcc608657ed2c",
  "1": "5a8755c66affcc608657ed2d"
}

This endpoint creates multiple new prices. Occurs automatically when you pass an array of price objects to this endpoint.

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",
  "code": "12346",
  "listName": "Price List for Canada",
  "startDate": "2018/01/01 00:00:00",
  "endDate": "2018/01/31 23:59:59",
  "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

Update Prices (bulk)

Request Body (JSON):

{
  "prices": [
    {
      "code": "12345",
      "listName": "Price List for USA",
      "startDate": "2018/01/01 00:00:00",
      "endDate": "2018/01/31 23:59:59",
      "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
    },
    {
      "code": "12346",
      "listName": "Price List for Canada",
      "startDate": "2018/01/01 00:00:00",
      "endDate": "2018/01/31 23:59:59",
      "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 code 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

Delete Prices (bulk)

Request Body (JSON):

[
  "5a8755c66affcc608657ed2c",
  "5a8755c66affcc608657ed2d"
]

Returns (JSON):

{
  "Deleted": 2
}

This endpoint deletes multiple prices by ID.

Endpoint

https://api.convictional.com/prices

Request example

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

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

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 (bulk)

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.

Endpoint

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)

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

Create Logs (bulk)

Request Body (JSON):

[
  {
    "description": "This is one log"
  },
  {
    "description": "This is another log"
  }
]

Returns (JSON):

{
  "0": "5a8755c66affcc608657ed2c",
  "1": "5a8755c66affcc608657ed2d"
}

This endpoint creates multiple new logs. Occurs automatically when you pass an array of log objects to this endpoint.

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

Update Logs (bulk)

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

Delete Logs (bulk)

Request Body (JSON):

[
  "5a8755c66affcc608657ed2c",
  "5a8755c66affcc608657ed2d"
]

Returns (JSON):

{
  "Deleted": 2
}

This endpoint deletes multiple logs by ID.

Endpoint

https://api.convictional.com/logs

Request example

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