Tap for Menu

Overview

API Endpoint:

URL: https://api.convictional.com

Welcome to the Convictional API. The purpose of the API is the same as the rest of our products: make it easier to sell to online retailers. Our customers and in-house development team use it.

Versioning

Last Updated:

Date: 2018-08-22

When breaking changes happen, we will notify users and migrate you. Our long-term goal is stability: B2B 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. To find your key, login to Convictional and go to "Settings". Include your API key in the "Authorization" header to authenticate your requests.

Other Headers

Other Headers:

Content-Type: application/json
Accept: application/json

We optionally accept Content-Type and Accept headers. We only support JSON, but in certain cases we can also work with text/plain types involving EDI documents. So assume JSON unless specified.

Rate Limits

The API does not have rate limits at this time. Our client library does queuing for you, or you can queue things yourself. If we change this policy in future, we will notify all our customers in advance.

Rate Limit Headers:

X-RateLimit-Limit: Unlimited
X-RateLimit-Remaining: Unlimited
X-RateLimit-Reset: Unlimited

Response Types

200: GET, POST or PUT Returns (JSON):

{
  "(content)"
}

200: DELETE Returns (JSON):

{
  "deleted": 1
}

200: Bulk PUT Returns (JSON):

{
  "updated": 2
}

400: Returns (JSON):

{
  "error": "not found"
}

401: Returns (JSON):

{
  "error": "unauthorized"
}

402+: Returns (JSON):

{
  "error": "(something you did wrong)"
}

500+: Returns (JSON):

{
  "error": "(something we did wrong)"
}

The API uses a variety of status codes to indicates success or failure of a particular request. The 200 series means success, the 400 series means something is wrong on your side, and the 500 series means something is wrong on our side. If you need help, contact support.

Custom Meta Data

Schema:

{
  "_id": "string",
  "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 only
json A JSON object can contain arbitrary JSON encoded data
boolean A boolean is either true or false
date A date in ISO 8601 format ("YYYY-MM-DDThh:mm:ss.sss-hh:mm")

The API deals in a variety of data types, always encoded in valid JSON. We support strings, dates, numbers and booleans. A JSON schema is provided for each resource and we will reject any incorrectly typed objects to ensure type safety across systems we connect to.

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. Other languages will be added as needed.

The client library will validate your request, check to make sure the right data is provided to perform a successful request 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.

Health & Status

Click here to see the health of the API at any time.

OK means online, anything else means the API is offline.

Request (HTTP):

GET https://api.convictional.com

Response (HTTP):

Body: OK
Status: 200

Actions

Action-oriented (RPC) endpoints that allow you to translate EDI documents, transmit files over FTP, invite your trading partners, onboard or offboard an account in our system, 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

Request Headers:

Content-Type: text/plain
Accept: application/json

Request (Text)

*segmentID*first*second*third~
*segmentID>first>second>third~
*segmentID>first>second>third~

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)

Document Types

Property Options Header Type Description
json in, out application/json This is a JSON document.
x12 in, out text/plain This is an EDI X12 document.

Use the 'Content-Type' header to signify the type of the inbound document and the 'Accept' header to signify the desired output type.

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?

Quick Order

Request Body (JSON)

{
  "source": "customer@domain.com",
  "subject": "convictional-wholesale",
  "items" : [
    {
      "sku": "ABC123",
      "quantity": 1
    },
    {
      "sku": "DEF456",
      "quantity": 2
    }
  ],
  "address": {
    "name": "First Last",
    "company": "Company, Inc",
    "phone": "4165555555",
    "email": "orders@customer.com",
    "type": "shipping",
    "city": "Toronto",
    "zip": "M5V4B3",
    "state": "Ontario",
    "country": "Canada",
    "address": "123 St.",
    "addressTwo": "#101"
  }
}

Success Returns (JSON)

{
  "success": true,
  "_id": "1542hhjasdfhj234"
}

Error Returns (JSON)

{
  "error": "message"
}

This endpoint creates an order in a supplier system on behalf of a partner, by email. The following conditions apply:

Quick Order Endpoint

https://api.convictional.com/handlers/emails/quickOrder

Quick Order Example

POST https://api.convictional.com/handlers/emails/quickOrder

Quick Order Properties

Property Type Required Description
source string Required Email of the partner ordering (or sales rep).
subject string Required CompanyId of the supplier / parent partner.
items array Required Items on the order (properties below)
address object Required Address to ship the order to.

Items Properties

Property Type Required Description
sku string Required SKU of the item.
quantity number Required Number of the item being requested.

Address Properties

Property Type Required Description
name string Required First and last name of the addressee
company string Optional Company name of the addressee
phone string Optional Phone number of the addressee
email string Optional Email of the addressee
type string Required Type of the addressee
city string Required City of the addressee
zip string Required Zip code or postal code of the addressee
state string Required State, province or territory of the addressee
country string Required Country of the addressee
addressOne string Required Address of the addressee
addressTwo string Optional Address extra line of the addressee

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

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",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "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",
        "properties": [
          {
            "type": "custom_engraving",
            "data": "We Love Dad!"
          }
        ],
        "grams": 200
      },
      {
        "title": "Great Standard Product",
        "quantity": 1,
        "price": 19.99,
        "sku": "35GRPRODUCT",
        "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",
        "properties": [
          {
            "type": "custom_engraving",
            "data": "We Love Dad!"
          }
        ],
        "grams": 200
      },
      {
        "title": "Great Standard Product",
        "quantity": 1,
        "price": 19.99,
        "sku": "35GRPRODUCT",
        "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",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "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",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "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",
      "properties": [
        {
          "type": "custom_engraving",
          "data": "We Love Dad!"
        }
      ],
      "grams": 200
    },
    {
      "title": "Great Standard Product",
      "quantity": 1,
      "price": 19.99,
      "sku": "35GRPRODUCT",
      "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",
          "properties": [
            {
              "type": "custom_engraving",
              "data": "We Love Dad!"
            }
          ],
          "grams": 200
        },
        {
          "title": "Great Standard Product",
          "quantity": 1,
          "price": 19.99,
          "sku": "35GRPRODUCT",
          "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",
          "properties": [
            {
              "type": "custom_engraving",
              "data": "We Love Dad!"
            }
          ],
          "grams": 200
        },
        {
          "title": "Great Standard Product",
          "quantity": 1,
          "price": 19.99,
          "sku": "35GRPRODUCT",
          "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):

{
  "updated": 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):

{
  "updated": 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?
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,
  "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,
    "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,
    "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)
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,
    "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,
  "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):

{
  "updated": 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):

{
  "updated": 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):

{
  "updated": 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

Changes

1.7 - 2018-07-16

1.6 - 2018-06-12

1.5 - 2018-06-08

1.4 - 2018-05-04

1.1 - 2018-03-28

1.0 - 2018-03-08