Getting Started with the Buyer API


In order to interact with the Convictional API, you need to have an API Key. This means you must first create an account via the signup page in our app.

Once you have an account you can find the API key in your settings page.

Your API Key can be found on the settings page of your account.

In order to authenticate against our API you send the API key in the Authentication property on all request headers. If the key is missing, you'll get an unauthorized response.

Getting your products

As a buyer, your account will only have products if you have successfully partnered with a seller and they have priced items for you. If that's done you can retrieve your items via the products GET endpoint like so:


This will return your items as an array of JSON objects.

Products contain a variety of properties but the one we're interested in right now is the variant._id property. This is the internal identifier for a variant and it's a required property when submitting orders via the Orders API. For now find a variant and copy-paste the variant ID into a safe place.

Creating an order

You can submit a new order through the API via the orders POST endpoint. A minimal request body may look something like this:

"address": {
"addressOne": "671 Lincoln Avenue",
"name": "Kevin McCallister",
"city": "Winnetka",
"state": "IL",
"country": "US",
"zip": "60093"
"items": [
"variantId": "1d61779c1ed12a5bbf13e4638271ac68",
"buyerReference": "InternalVariantID",
"quantity": 4
"buyerReference": "MyReferenceNumber",
"orderedDate": "2020-02-22T10:00:00.000Z",
"created": "2020-02-22T10:00:00.000Z",
"note": "Don't touch door."

Note that there is several properties that you can use to attach identifying information to an order to help you associate orders in your system with orders in Convictional. For example, the items.buyerReference should be the identifier that you use internally to identify a variant and the root level buyerReference is your internal identifier for the order as a whole.

The items.variantId property however must have the Convictional identifier for a variant which we found in the previous section when we retrieved products.

All together this request would be:

curl --request POST \ 
--url \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"address":{"addressOne":"671 Lincoln Avenue","name":"Kevin McCallister","city":"Winnetka","state":"IL","country":"US","zip":"60093"},"items":[{"variantId":"1d61779c1ed12a5bbf13e4638271ac68","buyerReference":"InternalVariantID","quantity":4}],"buyerReference":"MyReferenceNumber","orderedDate":"2020-02-22T10:00:00.000Z","created":"2020-02-22T10:00:00.000Z","note":"Please ship this extra fast"}'

If all goes well you will get a HTTP 200 response with the order ID as the body.

Getting recently updated orders

How did we do?