Overview

The Ordermate public API now available!

The Ordermate API lets you buy things from popular online retailers, including Amazon.com, with a single POST request. This documentation describes all of the available API calls and properties of the returned objects. If you have any questions, please reach out to development@ordermate.io.

At this time the Ordermate API is unstable. This means that the way it works and the data it returns may change at any time. Breaking changes are rare, but do happen. Proper versioning will be introduced in a future release.

The Ordermate API is organized around REST. Our API has predictable, resource-oriented URLs.

Getting Started

Create an account at ordermate.io.
Go through the Getting Started documentation to set up an ordermation to prepare your automated ordering.
Grab your API key from the integrations page and follow the directions in this documentation on how to create an order.

Authentication

You can authenticate your account by including your API token in your request. Authentication is performed through key={key} query string.

Make sure that you don’t share your API token and that you keep it away from publicly accessible areas such as Github, client-side code, etc. Client tokens are tied to your account, so you will be charged for any orders or requests made with your client token. If you believe your client token has been compromised, you can regenerate the token at any time by going to https://app.ordermate.io/integrations and pressing Generate New Token.

Ordermations

List all ordermations

GET

List all ordermations

GET /ordermations

https://api.ordermate.io/v1/ordermations?key={key}

Returns a list of all ordermations. The response is paginated and returns 10 ordermations by default. You can choose parse through each page and change the default number of ordermations per page by using the below query parameters.

Request Parameters

Name	In	Type	Required	Description
lookup	query	string	No	none
page	query	integer	No	none
perPage	query	integer	No	none

Responses

Status	Meaning	Description
200	OK	Example ordermation list response object

Ordermation Search Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
results	array	The results of ordermations returned
total	integer	The total numbers of all ordermations on your account
hasMore	boolean	Determines whether or not if the search result has more records
search	object	The search parameters that was passed with the query string

Example List Ordermation Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "total": 0,
  "hasMore": true,
  "query": {
    "value": "string",
    "page": 1,
    "perPage": 10
  },
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "publicId": 0,
      "name": "string",
      "createdDate": "2019-08-24T14:15:22Z",
      "modifiedDate": "2019-08-24T14:15:22Z",
      "status": "active",
      "shippingMethod": "cheapest",
      "maxPrice": 0,
      "retailer": {
        "code": "amazon",
        "name": "Amazon",
        "email": "you@email.com"
      },
      "shippingAddress": {
        "addressedTo": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "zip": "string",
        "phone": "+15099999999",
        "instructions": "string",
        "country": "string",
        "state": "string"
      },
      "paymentCard": {
        "cardholderName": "string",
        "expMonth": 2,
        "expYear": 2020,
        "type": "VISA",
        "last4": "0123"
      },
      "billingAddress": {
        "addressedTo": "string",
        "line1": "string",
        "line2": "string",
        "city": "string",
        "zip": "string",
        "phone": "+15099999999",
        "country": "string",
        "state": "string"
      },
      "items": [
        {
          "quantity": 0,
          "productId": "string",
          "name": "string",
          "brand": "string",
          "description": "string",
          "price": 0,
          "shipPrice": 0,
          "totalPrice": 0,
          "total": 0
        }
      ],
      "giftMessage": "string",
      "isGift": true,
      "useGift": true,
      "totalItems": 0,
      "totalPrice": 0,
      "totalShipping": 0,
      "total": 0,
      "createdBy": {
        "type": "user",
        "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
        "email": "you@email.com",
        "firstName": "string",
        "lastName": "string",
        "displayName": "string",
        "name": "string"
      }
    }
  ]
}

Retrieve an ordermation

GET

Retrieve an ordermation

GET /ordermations/{ordermationId}

https://api.ordermate.io/v1/ordermations/{ordermationId}?key={key}

Returns the ordermation details

Request Parameters

Name	In	Type	Required	Description
ordermationId	path	string	Yes	Ordermation ID

Responses

Status	Meaning	Description
200	OK	Example ordermation response object

Status Code 200

Ordermation Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
link	string	The direct link to the ordermation on Ordermate.
ordermation	object	ordermation

Example Get Ordermation Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "link": "https://app.ordermate.io/ordermation/497f6eca-6276-4993-bfeb-53cbbbba6f08/view",
  "ordermation": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "publicId": 0,
    "name": "string",
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "status": "active",
    "shippingMethod": "cheapest",
    "maxPrice": 0,
    "retailer": {
      "code": "amazon",
      "name": "Amazon",
      "email": "you@email.com"
    },
    "shippingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "instructions": "string",
      "country": "string",
      "state": "string"
    },
    "paymentCard": {
      "cardholderName": "string",
      "expMonth": 2,
      "expYear": 2020,
      "type": "VISA",
      "last4": "0123"
    },
    "billingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "country": "string",
      "state": "string"
    },
    "items": [
      {
        "quantity": 0,
        "productId": "string",
        "name": "string",
        "brand": "string",
        "description": "string",
        "price": 0,
        "shipPrice": 0,
        "totalPrice": 0,
        "total": 0
      }
    ],
    "giftMessage": "string",
    "isGift": true,
    "useGift": true,
    "totalItems": 0,
    "totalPrice": 0,
    "totalShipping": 0,
    "total": 0,
    "createdBy": {
      "type": "user",
      "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
      "email": "you@email.com",
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "name": "string"
    }
  }
}

Run ordermation

GET

Run ordermation

GET /ordermations/{ordermationId}/run

https://api.ordermate.io/v1/ordermations/{ordermationId}/run?key={key}

This is a simple trigger request that can be used to create new orders from this Ordermation. Each time this URL is visited, it will trigger a new order and show an order response. This is useful if you’d like to bookmark the URL in your browser or add it as a simple link in an internal ordering system. This does not support overriding any properties of the ordermation. It will simply run the ordermation as it is saved in your Ordermate account.

To add metadata, you can simply add multiple url encoded query parameters with the prefix md_. See the example below.

https://api.ordermate.io/v1/ordermations/{ordermationId}/run?key={key}&md_{metadata_key}={metadata_value}

When the order is created it will appear in the metadata object, and any query strings with the same md_keyname will become an array of multiple values

Please note, it is not recommended to use this method if you are concerned about security because it exposes your API key. We recommend using the POST Create New Order method for the most secure way of triggering an order.

Request Parameters

Name	In	Type	Required	Description
ordermationId	path	string	Yes	Ordermation ID

Responses

Status	Meaning	Description
200	OK	Example order response object

Status Code 200

Order Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
link	string	The direct link to the order on Ordermate.
order	object	The newly created order
metadata	object	The metadata that was passed when creating an order

Example Run Ordermation Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "link": "https://app.ordermate.io/order/497f6eca-6276-4993-bfeb-53cbbbba6f08/view",
  "order": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "publicId": 0,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "status": "completed",
    "retailer": {
      "code": "amazon",
      "name": "Amazon",
      "email": "you@email.com"
    },
    "shippingMethod": "cheapest",
    "maxPrice": 0,
    "requestId": "string",
    "api": {
      "message": "string"
    },
    "shippingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "instructions": "string",
      "country": "string",
      "state": "string"
    },
    "paymentCard": {
      "cardholderName": "string",
      "expMonth": 2,
      "expYear": 2020,
      "type": "VISA",
      "last4": "0123"
    },
    "billingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "country": "string",
      "state": "string"
    },
    "items": [
      {
        "quantity": 0,
        "productId": "string",
        "name": "string",
        "brand": "string",
        "description": "string",
        "link": "string",
        "price": 0,
        "shipPrice": 0,
        "totalPrice": 0,
        "total": 0
      }
    ],
    "totalItems": 0,
    "totalPrice": 0,
    "totalShipping": 0,
    "total": 0,
    "giftMessage": "string",
    "isGift": true,
    "useGift": true,
    "ordermation": {
      "id": "string",
      "name": "string"
    },
    "createdBy": {
      "type": "user",
      "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
      "email": "you@email.com",
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "name": "string"
    },
    "priceInfo": {
      "shipping": 0,
      "products": [
        {
          "price": 0,
          "sellerId": "string",
          "productId": "string",
          "quantity": 0
        }
      ],
      "subtotal": 0,
      "tax": 0,
      "total": 0,
      "giftCertificate": 0
    },
    "deliveryInfo": [
      {
        "date": "2019-08-24T14:15:22Z",
        "products": [
          {
            "productId": "string",
            "quantity": 0
          }
        ],
        "days": 0,
        "deliveryDate": "string"
      }
    ],
    "tracking": [
      {
        "merchantOrderId": "string",
        "carrier": "string",
        "trackingNumber": "string",
        "deliveryStatus": "string",
        "trackingUrl": "http://example.com",
        "productIds": [
          "string"
        ],
        "retailerTrackingNumber": "string",
        "retailerTrackingUrl": "http://example.com",
        "obtainedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "screenshots": [
      "http://example.com"
    ]
  },
  "metadata": {
    "custom": "string"
  }
}

Orders

List all orders

GET

List all orders

GET /orders

https://api.ordermate.io/v1/orders?key={key}

Returns a list of all orders. The response is paginated and returns 10 orders by default. You can choose parse through each page and change the default number of orders per page by using the below query parameters.

Request Parameters

Name	In	Type	Required	Description
lookup	query	string	No	none
page	query	integer	No	none
perPage	query	integer	No	none

Responses

Status	Meaning	Description
200	OK	Example order response object

Status Code 200

Order Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
link	string	The direct link to the order on Ordermate.
order	object	The newly created order
metadata	object	The metadata that was passed when creating an order

Example List Order Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "link": "https://app.ordermate.io/order/497f6eca-6276-4993-bfeb-53cbbbba6f08/view",
  "order": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "publicId": 0,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "status": "completed",
    "retailer": {
      "code": "amazon",
      "name": "Amazon",
      "email": "you@email.com"
    },
    "shippingMethod": "cheapest",
    "maxPrice": 0,
    "requestId": "string",
    "api": {
      "message": "string"
    },
    "shippingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "instructions": "string",
      "country": "string",
      "state": "string"
    },
    "paymentCard": {
      "cardholderName": "string",
      "expMonth": 2,
      "expYear": 2020,
      "type": "VISA",
      "last4": "0123"
    },
    "billingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "country": "string",
      "state": "string"
    },
    "items": [
      {
        "quantity": 0,
        "productId": "string",
        "name": "string",
        "brand": "string",
        "description": "string",
        "link": "string",
        "price": 0,
        "shipPrice": 0,
        "totalPrice": 0,
        "total": 0
      }
    ],
    "totalItems": 0,
    "totalPrice": 0,
    "totalShipping": 0,
    "total": 0,
    "giftMessage": "string",
    "isGift": true,
    "useGift": true,
    "ordermation": {
      "id": "string",
      "name": "string"
    },
    "createdBy": {
      "type": "user",
      "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
      "email": "you@email.com",
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "name": "string"
    },
    "priceInfo": {
      "shipping": 0,
      "products": [
        {
          "price": 0,
          "sellerId": "string",
          "productId": "string",
          "quantity": 0
        }
      ],
      "subtotal": 0,
      "tax": 0,
      "total": 0,
      "giftCertificate": 0
    },
    "deliveryInfo": [
      {
        "date": "2019-08-24T14:15:22Z",
        "products": [
          {
            "productId": "string",
            "quantity": 0
          }
        ],
        "days": 0,
        "deliveryDate": "string"
      }
    ],
    "tracking": [
      {
        "merchantOrderId": "string",
        "carrier": "string",
        "trackingNumber": "string",
        "deliveryStatus": "string",
        "trackingUrl": "http://example.com",
        "productIds": [
          "string"
        ],
        "retailerTrackingNumber": "string",
        "retailerTrackingUrl": "http://example.com",
        "obtainedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "screenshots": [
      "http://example.com"
    ]
  },
  "metadata": {
    "custom": "string"
  }
}

Retrieve an order

GET

Retrieve an order

GET /orders/{orderId}

https://api.ordermate.io/v1/orders/{orderId}?key={key}

Returns the order details

Request Parameters

Name	In	Type	Required	Description
orderId	path	string	Yes	OrderId

Responses

Status	Meaning	Description
200	OK	Example order response object

Status Code 200

Order Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
link	string	The direct link to the order on Ordermate.
order	object	The newly created order
metadata	object	The metadata that was passed when creating an order

Example Get Order Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "link": "https://app.ordermate.io/order/497f6eca-6276-4993-bfeb-53cbbbba6f08/view",
  "order": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "publicId": 0,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "status": "completed",
    "retailer": {
      "code": "amazon",
      "name": "Amazon",
      "email": "you@email.com"
    },
    "shippingMethod": "cheapest",
    "maxPrice": 0,
    "requestId": "string",
    "api": {
      "message": "string"
    },
    "shippingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "instructions": "string",
      "country": "string",
      "state": "string"
    },
    "paymentCard": {
      "cardholderName": "string",
      "expMonth": 2,
      "expYear": 2020,
      "type": "VISA",
      "last4": "0123"
    },
    "billingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "country": "string",
      "state": "string"
    },
    "items": [
      {
        "quantity": 0,
        "productId": "string",
        "name": "string",
        "brand": "string",
        "description": "string",
        "link": "string",
        "price": 0,
        "shipPrice": 0,
        "totalPrice": 0,
        "total": 0
      }
    ],
    "totalItems": 0,
    "totalPrice": 0,
    "totalShipping": 0,
    "total": 0,
    "giftMessage": "string",
    "isGift": true,
    "useGift": true,
    "ordermation": {
      "id": "string",
      "name": "string"
    },
    "createdBy": {
      "type": "user",
      "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
      "email": "you@email.com",
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "name": "string"
    },
    "priceInfo": {
      "shipping": 0,
      "products": [
        {
          "price": 0,
          "sellerId": "string",
          "productId": "string",
          "quantity": 0
        }
      ],
      "subtotal": 0,
      "tax": 0,
      "total": 0,
      "giftCertificate": 0
    },
    "deliveryInfo": [
      {
        "date": "2019-08-24T14:15:22Z",
        "products": [
          {
            "productId": "string",
            "quantity": 0
          }
        ],
        "days": 0,
        "deliveryDate": "string"
      }
    ],
    "tracking": [
      {
        "merchantOrderId": "string",
        "carrier": "string",
        "trackingNumber": "string",
        "deliveryStatus": "string",
        "trackingUrl": "http://example.com",
        "productIds": [
          "string"
        ],
        "retailerTrackingNumber": "string",
        "retailerTrackingUrl": "http://example.com",
        "obtainedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "screenshots": [
      "http://example.com"
    ]
  },
  "metadata": {
    "custom": "string"
  }
}

Create new order

POST

Create new order

POST /orders

https://api.ordermate.io/v1/orders?key={key}

Creating a new order can be done a couple different ways.

Create a new order from an ordermation - simply pass the ordermationID, all other fields are optional in case you want to override some properties of the ordermation (i.e. shipping address)
Create a new custom order - no ordermation required, but all of the additional properties are required

Create New Order Request

When creating an order from an ordermation, it can be as simple as passing the ordermationID in the request along with your API key which will trigger the order as it was saved in your ordermation. You can also pass along any additional properties to override certain properties in the ordermation like a new address or a new payment card, etc.

Property	Type	Required	Description
ordermationId	integer or uuid	Yes	You can pass the ordermation ID which can be found on the page when viewing an ordermation. This field accepts either the ordermation’s public ID or the UUID formatted ID
credentials	object	Yes	The retailer credentials that will be required to process this order.
shippingMethod	string	No	`cheapest` `free` `fastest` For more information see shipping method options.
maxPrice	float	No	The maximum price allowed to process this order.
shippingAddress	object	No	The shipping address that will be passed when creating an order.
paymentCard	object	No	The payment card that will be passed when creating the order.
billingAddress	object	No	The billing address that will be passed when creating the order.
giftMessage	string	No	The gift message that will be passed when creating the order
isGift	boolean	No	Whether or not this order is a gift.
useGift	boolean	No	Whether or not this order will use a gift card balance instead of the payment card.
items	array	No	The create order items that will be passed when creating the order.
itemsQuantity	integer	No	Allows to override all the order items with the specific quantity. If you assign `0` or `null`, it will be ignored and not used. If you override `items` this also will be ignored. *Note this will also automatically adjust the `maxPrice` if you do not override the `maxPrice`.
advancedSettings	object	No	The advanced settings that will be used to filter out which order offer.
metadata	boolean	No	The metadata that will be passed when creating the order.

Create Order Items

Property	Type	Required	Description
quantity	integer	Yes	The number of products to purchase.
productId	string	Yes	The retailer’s unique identifier for the product. Note that Ordermate does not support digital purchases or Amazon prime pantry items.
advancedSettings	object	No	The advanced settings that will be used to filter out which order offer.
~~sellerSelectionCriteria~~	object	No	This field has been replaced with advancedSettings. However this will remain for back-compatability and has been marked deprecated and will be removed in future releases.

Responses

Status	Meaning	Description
200	OK	Example order response object

Status Code 200

Order Response

Property	Type	Description
version	string	The Version of the API Response.
versionCode	integer	The Version Code of the API Response. First segment is the Major version, next two segments is the minor and the last 4 is the patch. Example: 10001 will be “0.1.1”. This is useful for comparing previous versions.
status	object	The returned status, this is used to determine whether the order passed or failed, along with standard HTTP StatusCodes
link	string	The direct link to the order on Ordermate.
order	object	The newly created order
metadata	object	The metadata that was passed when creating an order

Example Create Order Request Body

{
  "ordermationId": "d840ad83-aa63-4a40-b542-e6a7e1df1ed5",
  "credentials": {
    "email": "you@email.com",
    "password": "pa$$word",
    "optKey": "string",
    "optType": "app"
  },
  "shippingMethod": "cheapest",
  "maxPrice": 0,
  "shippingAddress": {
    "addressedTo": "string",
    "line1": "string",
    "line2": "string",
    "country": "string",
    "state": "string",
    "city": "string",
    "zip": "string",
    "phone": "+15099999999",
    "instructions": "string"
  },
  "billingAddress": {
    "addressedTo": "string",
    "line1": "string",
    "line2": "string",
    "country": "string",
    "state": "string",
    "city": "string",
    "zip": "string",
    "phone": "+15099999999"
  },
  "isGift": true,
  "giftMessage": "string",
  "paymentCard": {
    "cardholderName": "string",
    "number": "string",
    "expMonth": 0,
    "expYear": 0,
    "cvv": "string"
  },
  "useGift": true,
  "items": [
    {
      "productId": "string",
      "quantity": 0,
      "advancedSettings": {
        "conditionsIn": [
          "string"
        ],
        "conditionsNotIn": [
          "string"
        ],
        "firstPartySeller": true,
        "international": true,
        "handlingDaysMax": 0,
        "maxItemPrice": 0,
        "addon": true,
        "buyBox": true,
        "merchantIdsIn": [
          "string"
        ],
        "merchantIdsNotIn": [
          "string"
        ],
        "minSellerRating": 0,
        "minSellerPercentPositiveFeedback": 0,
        "primeOnly": true
      }
    }
  ],
  "itemsQuantity": 0,
  "advancedSettings": {
    "conditionsIn": [
      "string"
    ],
    "conditionsNotIn": [
      "string"
    ],
    "firstPartySeller": true,
    "international": true,
    "handlingDaysMax": 0,
    "maxItemPrice": 0,
    "addon": true,
    "buyBox": true,
    "merchantIdsIn": [
      "string"
    ],
    "merchantIdsNotIn": [
      "string"
    ],
    "minSellerRating": 0,
    "minSellerPercentPositiveFeedback": 0,
    "primeOnly": true
  },
  "metadata": {
    "custom": "your custom value you want to pass that will be passed and included in the output"
  }
}

Example Create Order Response Body

200 Response

{
  "version": "1.0.0",
  "versionCode": 0,
  "status": {
    "phrase": "string",
    "type": "string",
    "source": "string",
    "code": 0,
    "params": {},
    "message": "string"
  },
  "link": "https://app.ordermate.io/order/497f6eca-6276-4993-bfeb-53cbbbba6f08/view",
  "order": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "publicId": 0,
    "createdDate": "2019-08-24T14:15:22Z",
    "modifiedDate": "2019-08-24T14:15:22Z",
    "status": "completed",
    "retailer": {
      "code": "amazon",
      "name": "Amazon",
      "email": "you@email.com"
    },
    "shippingMethod": "cheapest",
    "maxPrice": 0,
    "requestId": "string",
    "api": {
      "message": "string"
    },
    "shippingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "instructions": "string",
      "country": "string",
      "state": "string"
    },
    "paymentCard": {
      "cardholderName": "string",
      "expMonth": 2,
      "expYear": 2020,
      "type": "VISA",
      "last4": "0123"
    },
    "billingAddress": {
      "addressedTo": "string",
      "line1": "string",
      "line2": "string",
      "city": "string",
      "zip": "string",
      "phone": "+15099999999",
      "country": "string",
      "state": "string"
    },
    "items": [
      {
        "quantity": 0,
        "productId": "string",
        "name": "string",
        "brand": "string",
        "description": "string",
        "link": "string",
        "price": 0,
        "shipPrice": 0,
        "totalPrice": 0,
        "total": 0
      }
    ],
    "totalItems": 0,
    "totalPrice": 0,
    "totalShipping": 0,
    "total": 0,
    "giftMessage": "string",
    "isGift": true,
    "useGift": true,
    "ordermation": {
      "id": "string",
      "name": "string"
    },
    "createdBy": {
      "type": "user",
      "id": "4a3a0c84-3fce-4e7d-949a-afc490c0aaeb",
      "email": "you@email.com",
      "firstName": "string",
      "lastName": "string",
      "displayName": "string",
      "name": "string"
    },
    "priceInfo": {
      "shipping": 0,
      "products": [
        {
          "price": 0,
          "sellerId": "string",
          "productId": "string",
          "quantity": 0
        }
      ],
      "subtotal": 0,
      "tax": 0,
      "total": 0,
      "giftCertificate": 0
    },
    "deliveryInfo": [
      {
        "date": "2019-08-24T14:15:22Z",
        "products": [
          {
            "productId": "string",
            "quantity": 0
          }
        ],
        "days": 0,
        "deliveryDate": "string"
      }
    ],
    "tracking": [
      {
        "merchantOrderId": "string",
        "carrier": "string",
        "trackingNumber": "string",
        "deliveryStatus": "string",
        "trackingUrl": "http://example.com",
        "productIds": [
          "string"
        ],
        "retailerTrackingNumber": "string",
        "retailerTrackingUrl": "http://example.com",
        "obtainedAt": "2019-08-24T14:15:22Z"
      }
    ],
    "screenshots": [
      "http://example.com"
    ]
  },
  "metadata": {
    "custom": "string"
  }
}

Webhooks

Webhooks let you register a URL that the Ordermate API notifies whenever an event happens pertaining to your account. When an event occurs, we will send a POST request to the URL specified in the webhooks object. If no URL was specified, then a webhook will not be sent. The body of the POST request is the standard raw JSON response for that object.

For example, once an order has been created on Ordermate, Every time the order status changes, a POST request will be sent to the endpoint that you have created. The body will mimic the response received from the standard GET https://api.ordermate.io/v1/orders/{orderId} request.

You can create a new webhook endpoint on the integrations page on Ordermate.

Order Status Changed

Events

order_status_changed

Property	Type	Description
event	object	The event
link	string	The direct link to the order on Ordermate.
order	object	The order that contains information that was changed.
status	enum	The current order status.
oldStatus	enum	The previous order status.
message	string	The response message.
tracking	array	A list of tracking information obtained by the retailer.
priceInfo	object	The price information about the order obtained by the retailer.
deliveryInfo	array	A list of delivery information obtained by the retailer.
merchantOrders	array	A list of merchant order information obtained by the retailer.
accountStatus	object	(Amazon only) The account status that gives details about the ordering account.

API References

Order Object

Property	Type	Description
id	uuid	The unique ID that represents this order.
publicId	integer	The unique ID that represents this order that is unqiuely to your account.
createdDate	timestamp	The timestamp that this order was created on.
modifiedDate	timestamp	The timestamp that this order was last modified on.
status	string	List of order statuses can be found here
retailer	object	The retailer account that was passed when creating an order.
shippingMethod	string	`cheapest` `free` `fastest` For more information see shipping method options.
maxPrice	float	The maximum price allowed to process on this order.
requestId	string	The unique ID that represents this order that created the request.
api	object	The object that contains an `error message` that occured while processing the request.
shippingAddress	object	The shipping address that was passed when creating an order.
paymentCard	object	The payment card that was passed when creating an order.
billingAddress	object	The billing address that was passed when creating an order.
totalItems	integer	The total items on this order.
totalPrice	float	The total price of all items on this order.
totalShipping	float	The total shipping cost of all items on this order.
total	float	The total price of all items on this order (includes both shipping and price).
giftMessage	string	The gift message that was sent with this order.
isGift	boolean	Whether or not this order was a gift.
useGift	boolean	Whether or not this order used a gift card balance instead of the payment card that was passed.
items	array	The order items that was passed when creating an order.
ordermation	object	The ordermation that was used when creating this order.
createdBy	object	An object that contains information who created this order.
metadata	object	The metadata that was passed when creating an order.

Order Extended Data

This information is only shown GET /orders/{orderId} and POST /orders/ endpoints.

Property	Type	Description
screenshots	array	A list of screenshots (images and can contain a PDF document as well) that was returned when processing your order.
tracking	array	A list of tracking information obtained by the retailer.
priceInfo	object	The price information about the order obtained by the retailer.
deliveryInfo	array	A list of delivery information obtained by the retailer.
merchantOrders	array	A list of merchant order information obtained by the retailer.
accountStatus	object	(Amazon only) The account status that gives details about the ordering account.

Order Status

Order Status	Description
`scheduled`	This order is scheduled to be processed on a specific date and at a specific time.
`pending`	This order has been requested and will be submitted soon.
`queued`	This order has been requested and is queued for launch.
`busy`	The retailer account is currently in-use. This order will continue once the retailer account is no longer in-use.
`launched`	This order is currently in-progress and will complete soon.
`completed`	This order has been made successfully.
`shipped`	This order has been shipped and will be delivered to the Shipping Address provided on the order soon.
`delivered`	This order has been successfully delivered to the Shipping Address provided on the order.
`failed`	On the order object will contain a body parameter called `api` that will contain any failed messages.
`aborted`	This order was manually aborted.
`cancelling`	This order is attempting to cancel. In about 50% of cases, Amazon is unable to immediately cancel an order. This status will be updated when the order is either cancelled successfully or if the cancellation fails.
`cancelled`	This order has been successfully cancelled.

Order Item Object

Property	Type	Description
quantity	integer	The number of products to purchase.
productId	string	The retailer’s unique identifier for the product. Note that Ordermate does not support digital purchases or Amazon prime pantry items.
name	string	The name of the product.
brand	string	The brand that owns this product.
description	string	The description about this product.
link	string	The direct retailer link to the product.
price	float	The price cost that was obtained at the time of creating this order.
shipPrice	float	The ship price cost that was obtained at the time of creating this order.
totalPrice	float	The total price that was obtained at the time of creating this order (quantity * price).
total	float	The total cost that was obtained at the time of creating this order (totalPrice + shipPrice).

Ordermation Object

Property	Type	Description
id	uuid	The unique ID that represents this ordermation.
publicId	integer	The unique ID that represents this ordermation that is unqiuely to your account.
createdDate	timestamp	The timestamp that this ordermation was created on.
modifiedDate	timestamp	The timestamp that this ordermation was last modified on.
status	string	`active` `in-active` `deleted`
retailer	object	The retailer account that will be sent with the order upon creation.
shippingMethod	string	`cheapest` `free` `fastest` For more information see shipping method options.
maxPrice	float	The maximum price allowed to process on this ordermation.
shippingAddress	object	The shipping address that will be sent with the order upon creation.
paymentCard	object	The payment card that will be sent with the order upon creation.
billingAddress	object	The billing address that will be sent with the order upon creation.
giftMessage	string	The gift message that will be sent with the order upon creation.
isGift	boolean	Whether or not this order was a gift.
useGift	boolean	Whether or not this order used a gift card balance instead of the payment card that was passed.
items	array	The ordermation items that will be sent with the order upon creation.
totalItems	integer	The total items on this order.
totalPrice	float	The total price of all items on this order.
totalShipping	float	The total shipping cost of all items on this order.
total	float	The total price of all items on this order (includes both shipping and price).
createdBy	object	An object that contains information who created this ordermation.

Ordermation Item Object

Property	Type	Description
quantity	integer	The number of products to purchase.
productId	string	The retailer’s unique identifier for the product. Note that Ordermate does not support digital purchases or Amazon prime pantry items.
name	string	The name of the product.
brand	string	The brand that owns this product.
description	string	The description about this product.
link	string	The direct retailer link to the product.
price	float	The price cost that was obtained at when adding the product to Ordermate.
shipPrice	float	The ship price cost that was obtained at when adding the product to Ordermate.
totalPrice	float	The total price that was obtained at when adding the product to Ordermate (quantity * price).
total	float	The total cost that was obtained at when adding the product to Ordermate (totalPrice + shipPrice).

Payment Card Object

Property	Type	Description
cardholderName	string	The name of the card holder.
expMonth	integer	The month that this card will expire.
expYear	integer	The year that this card will expire.
type	string	The type of card.
last4	string	The last 4 digits of the payment card.

Billing Address Object

Property	Type	Description
addressedTo	string	The name of the person that will be addressed to.
line1	string	The house number and street name.
line2	string	The suite, post office box, or apartment number.
city	string	The city of the address.
zip	string	The zip code of the address.
phone	string	The phone number associated with the address.
country	string	The ISO abbreviation for the country of the address (e.g. US). A list of all available two-letter country codes can be found here.
state	string	The USPS abbreviation for the state of the address (e.g. AK).

Shipping Address Object

Property	Type	Description
addressedTo	string	The name of the person that will be addressed to.
line1	string	The house number and street name.
line2	string	The suite, post office box, or apartment number.
city	string	The city of the address.
zip	string	The zip code of the address.
phone	string	The phone number associated with the address.
country	string	The ISO abbreviation for the country of the address (e.g. US). A list of all available two-letter country codes can be found here.
state	string	The USPS abbreviation for the state of the address (e.g. AK).
instructions	string	Optional instructions to include with the shipping addresses.

Retailer Account Object

Property	Type	Description
code	string	`amazon`
name	string	The name of the retailer.
email	email	The email that is associated with this retailer account.

Shipping Method Options

The ordering of available shipping methods that meet the desired criteria. Available values are price or speed. If ordering by price, then the Ordermate API will choose the cheapest shipping method that meets the desired criteria, while speed will choose the fastest shipping method meeting the criteria.

Option	Description
cheapest
free
fastest

Price Information Object

Property	Type	Description
shipping	number	The shipping amount.
products	array	List of price information about each product items.
subtotal	number	The subtotal of this order.
tax	number	The tax of this order.
total	number	The total of the order.
giftCertificate	number

Product Item

Property	Type	Description
price	number	The price that was obtained by the retailer.
sellerId	string	The seller identification used by the retailer.
productId	string	The retailer’s product id that represents this product.
quantity	integer	The quantity.

NOTE: As of API Version 0.3.8, the price/shipping/tax/total/subtotal previously was in cents, this is now in decimal precision. Ex: 1000 = 10.00. If the API version is not included it retains the same value in cents.

Tracking Information Object

Property	Type	Description
merchantOrderId	string	The merchant order ID obtained by the retailer.
carrier	string	The tracking carrier delivering this order.
trackingNumber	string	The tracking number provided by the carrier.
deliveryStatus	string	The delivery status of this order.
trackingUrl	string	The delivery tracking URL provided by the carrier.
productIds	array	A list of product IDS, there will be duplicates based on the amount of quantity provided.
retailerTrackingNumber	string	The retailer tracking number.
retailerTrackingUrl	string	The retailer tracking URL.
obtainedAt	datetime	The timestamp that this tracking information was obtained by the retailer.

Delivery Information Object

Property	Type	Description
date	datetime	The delivery date obtained by the retailer.
products	array	The list of products being sent.
days	integer	The number of days estimated to be delivered.
deliveryDate	datetime	The user friendly delivery date obtained by the retailer.

Product Item

Property	Type	Description
productId	string	The retailer’s product id that represents this product.
quantity	integer	The quantity obtained by the retailer.

Merchant Order Information Object

Property	Type	Description
account	string	The email associated with the retailer.
merchant	string	The retailer merchant.
shippingAddress	string	The shipping address provided by the merchant. This is the address all of the products in the `productIds` are going to be delievered to.
placedAt	datetime	The date of when the order was placed at by the merchant.
productIds	array	A list of all product ids.
trackingUrl	string	The delivery tracking URL provided by the merchant.
deliveryDate	string	A user friendly string of when the products should be delivered by.
merchantOrderId	string	The merchant order ID obtained by the retailer.

Account Status Object

Property	Type	Description
isPrime	boolean	Indicates if the account has Prime enabled.
isFresh	boolean	Indicates if the account has Fresh enabled.
taxExemptStates	array	A list of states that this account has tax exemption.
isBusiness	boolean	Indicates if the account has Business enabled.
charity	string	Indicates if the account has a Charity associated.

Advanced Settings Object

Property	Type	Description
conditionsIn	array	An array of item conditions (string) that the Ordermate must order from. (Common conditions are: `New` `Used`)
conditionsNotIn	array	An array of item conditions (string) that the Ordermate must NOT order from. (Common conditions are: `New` `Used`)
firstPartySeller	boolean	Is the seller first-party? e.g. sold by Walmart.com on walmart.
handlingDaysMax	integer	The maximum number of allowable days for shipping and handling.
international	boolean	Specifies whether the item should come from an international supplier.
maxItemPrice	number	The maximum allowable price for an item.

(Amazon Only)

Property	Type	Description
addon	boolean	Specifies whether the selected offer should be an addon item.
buyBox	boolean	Specifies whether the selected offer should be Amazon’s default buy box offer.
merchantIdsIn	array	An array of merchant ids (string) that the Ordermate must order from.
merchantIdsNotIn	array	An array of merchant ids (string) that the Ordermate must NOT order from.
minSellerRatings	integer	The minimum number of ratings required for an Amazon seller’s offer to be selected.
minSellerPercentPositiveFeedback	integer	The minimum percentage of positive ratings of an Amazon seller for their offer to be selected. (Range from 0-100)
primeOnly	boolean	Specifies whether the selected offer should be an Amazon Prime offer.

Status Object

Property	Type	Description
code	integer	This is the status code, if it is equal to 0 then it is successful
type	string	`internal` `success` `error`
message	string	User friendly error message

Search Object

Property	Type	Description
lookup	string	The query value to search against.
page	integer	The page number passed during the search.
perPage	integer	The total records passed, ranges from 1 to 100.

Metadata Object

Any metadata to store on the request for future use. This object will be passed back in the response.

Metadata example:

{
  "value1": "0123456789",
  "value2": [
    "1", "2", "3"
  ]
}

Event Object

Property	Type	Description
id	uuid	The id of this event subscription.
name	string	The name of this event subscription triggered.

Errors

The Ordermate API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your API key is wrong.
403	Forbidden – The ordermate requested is hidden for administrators only.
404	Not Found – The specified ordermate could not be found.
405	Method Not Allowed – You tried to access a ordermate with an invalid method.
406	Not Acceptable – You requested a format that isn’t json.
410	Gone – The ordermate requested has been removed from our servers.
418	I’m a teapot.
429	Too Many Requests – You’re requesting too many requests on ordermate! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.