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.

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:

curl --request GET \ 
--url \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_API_KEY'

This will return your items as an enveloped response and within "data" is 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

Once an order was made there are currently 4 statuses that you can monitor to see how the order is progressing:

- posted

- fulfilled

- invoiced

- refunded

You can read a little more about how that all works here.

Since you can create an order for many different variants, from different vendors, Convictional will identify the appropriate orders to create in the sellers system. The posted flag tells you if that has happened.

Once a vendor has your order it's up to them to ship that item to the customer. The fulfilled flag on a seller order tells you if that has happened. Fulfilled will only be true once all the line items of that sellers order are shipped.

You can access orders you've made via the buyer orders GET endpoint. Alternatively if you know the Convictional order ID you can also access a specific order via the buyer GET order by ID endpoint.

To monitor for recently changed orders you can use the updatedMin query parameter like so:

curl --request GET \ 
--url '' \
--header 'Accept: application/json' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \

How did we do?

Getting Started with Webhooks

How to Create an Order for the Buyer API