Getting Started

Welcome to the official OrderMerch documentation. Our goal is to make this process as simple as possible. Fulfillment shouldn't be hard and neither should our implementation.

To get started you'll need to know a few things:

• Your API Key
• The endpoint(s) you need to use
  • For placing an order
  • For retrieving all your products
  • Etc
• All items are in USD by default
• All datetimes are UTC

All integrations must comply with the OrderMerch Terms and OrderMerch API Terms.

Requests resulting in an error response must not exceed 5% of your total requests.

We reserve the right at any time with or without notice to change or depreciate our APIs. In most cases, we give ample notice and send an email. These notifications will be sent to the companies email in your API settings.

Authentication

The OrderMerch API uses API keys to authenticate requests. You can view an API key for each company your account has access to in the OrderMerch dashboard.

To get access to your API key, create an account here and confirm your email address.

All API keys are in live mode, at this time we do not offer an API for testing.

Currently API keys have all privileges, so be sure to keep them secure and private! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

How to do this is beyond the scope of this documentation. A brief example from Twilio by using environmental variables can be watched here.

You'll use your API key by assigning X-API-KEY to the headers of your request and set the value to your API key. An example of this is as follows.

Headers

X-API-KEY: 743....7b2628d.....da5.....4a

Responses

HTTP 200 OK

HTTP 401 Unauthorized

All API endpoints can return a 401 status code with the response shown above.

Pagination

All top-level API resources have support for bulk fetches through a list API method. For example, you're able to list products, and orders. These list API methods share a common structure allowing you to provide a single page number in the request query parameters.

Request:

GET https://api.ordermerch.net/v1/products/?page=4

Response:

HTTP 200 OK

If an API resource supports pagination they will have the tag pagination.

Get All Products

You're able to fetch all products that are attached to a company. This will paginate and return each individual product with the BaseProduct, Variants, BaseVariant, Options and more.

All users are limited to 200 requests per day for products. - We recommend you save or cache the results.

Request:

GET https://api.ordermerch.net/v1/products/?page=1

Responses:

HTTP 200 OK

Place an Order

You're able to send us an order with details such as the line items, shipping address, and the values associated with those objects. All requests are handled asynchronously and you will need to check the status of an order after placing it.

Body

Key	Tags	Description
line_items	required, non-empty	Array of objects (PlacedLineItem)
shipping_address	required	object (Address)

Request:

POST https://api.ordermerch.net/v1/orders/place/

Responses:

HTTP 200 OK

HTTP 400 Bad Request

After placing an order you're returned a task ID. You'll want to check this task ID after 30+ seconds to ensure that there wasn't a problem with creating your order.

You can get the response of a placed order below.

If there was a problem, you'll need to make changes and replace your order.

The responses for this endpoint are subject to change. You'll want to check for an OK status code.

Get an Orders Response

After you've placed an order you'll need to check the response. This is required as orders can be dispatched to multiple suppliers and can possibly take a few minutes. If there was a problem with your order you'll need to make the requested changes and re-place an order.

Request:

GET http://127.0.0.1:8000/v1/orders/place/{uuid}/

Responses:

HTTP 200 OK

HTTP 206 Partial Content

The order is still pending and hasn't been completely processed.

HTTP 400 Bad Request

There was a problem placing your order. You'll need to make the requested changes if shown and try again.

 

HTTP 401 Unauthorized

You're not authenticated or don't have access to this order.

Get an Order

You're able to get an Order by UUID. This allows you to check the status, shipments, and more.

Request:

GET https://api.ordermerch.net/v1/orders/{uuid}/

Responses:

HTTP 200 OK

HTTP 404 Not Found

Cancel an Order

You're able to cancel an Order by its UUID. An order can only be cancelled if the status is Pending. By cancelling an order it will not be processed further.

Request:

DELETE https://api.ordermerch.net/v1/orders/{uuid}/cancel/

Responses:

HTTP 200 OK

HTTP 404 Not Found

Update an Order

Unfortunately, we do not allow updating an Order. Instead, you'll need to cancel the Order and then place it again with the new details.

Process an Order

Approves an Order for fulfillment. The companies default credit card is charged when the order is submitted for processing. This changes the Order status to Pending and the Order can no longer be updated or cancelled.

Request:

POST https://api.ordermerch.net/v1/orders/{uuid}/process/

Responses:

HTTP 200 OK

HTTP 400 Bad Request

The responses for this endpoint are subject to change.

All Countries

You're able to fetch all countries that are available with OrderMerch. You'll need to provide the alpha_three_code when placing an order.

All users are limited to 100 requests per day for countries. - We recommend you save the results as these rarely update or change.

Our specification for countries are based on ISO 3166-1.

Can can include subdivisons (eg. provinces or states). If a country has a subdivision(s) you'll need to provide the code for the state_or_province on an Address.

If a country requires a postal code you'll need to provide a zip_or_postal_code for an Address.

You're able to search/filter based on the following query parameters.

Key	Tags
name	string
alpha_two_code	string
alpha_three_code	string
numeric_code	string
requires_postal_code	boolean

Request:

GET https://api.ordermerch.net/v1/geographic/countries?alpha_three_code=CAN

Responses:

HTTP 200 OK

Webhooks

You can use webhooks to receive notifications about particular events for a company. After you've added a postback URL, you can listen for events to trigger an action in your app. For example, once an order has been marked as shipped your app will receive an event. You can trigger a series of events such as emailing a customer that their order has been shipped.

Data sent to your application will always be a POST request. Your server needs to return a 200 status code. We only send a webhook event one time. Your server will need to handle any errors that might occur, and process the event properly. If you have an error we recommend logging it for reprocessing or try manually fetching the order to see the current status.

We only send webhook data for an Order. The data is of the entire order. To determine what type of event the webhook is you'll need to refer to the status of the Order. For example, an Order with a status of Problem would mean that there was a problem with order and you'll need to contact support for assistance.

Status	Description
Shipping	The order has sent out a shipment. Other items still need to be shipped.
Completed	The order has sent out all shipments. The order is now considered complete.
Cancelled	The order was cancelled. This order will not be updated anymore.
Problem	There was a problem with the order. You'll need to contact support for assistance. A shipment could have been returned, the order may require addition information, etc.

Endpoint:

POST https://your-domain.com/ordermerch/webhook

Address

Key	Tags
first_name	required, string [ 1 .. 35 ] characters
last_name	required, string [ 1 .. 35 ] characters
email	required, string email [ 1 .. 254 ] characters
address	required, string [ 1 .. 50 ] characters
address_two	string [ 1 .. 50 ] characters
city	required, string [ 1 .. 32 ] characters
country	required, string [ 1 .. 56 ] characters, alpha_three_code from Country
state_or_province	string [ 1 .. 255 ] characters, name from Subdivision, required if a country has subdivisions
zip_or_postal_code	string [ 1 .. 32 ] characters, required if a country has the field requires_postal_code
company	string [ 1 .. 35 ] characters
phone_number	recommended, required for some countries, string [ 1 .. 18 ] characters

Example:

Country

Key	Tags
name	required, string [ 1 .. 255 ] characters
alpha_two_code	required, string [ 1 .. 2 ] characters
alpha_three_code	required, string [ 1 .. 3 ] characters
numeric_code	required, string [ 1 .. 3 ] characters
requires_postal_code	required, boolean
subdivisions	required, Array of objects Subdivision

Example:

Subdivision

Key	Tags
name	required, string [ 1 .. 255 ] characters
code	required, string [ 1 .. 6 ] characters
iso	string
category	string

Example:

PlacedLineItem

Key	Tags
product_uuid	required, string uuid
variant_uuid	required, string uuid
quantity	integer, default 1

Example:

Order

Key	Tags
uuid	required, string uuid
created_at	required, string datetime
updated_at	required, string datetime
is_active	required, boolean
status	required, string [Pending, In Progress, Completed, Shipping, Cancelled, Problem]
total	required, string decimal
subtotal	required, string decimal
subtotal_currency	required, string [USD, CAD]
shipping	required, string decimal
shipping_currency	required, string [USD, CAD]
tax	required, string decimal
tax_currency	required, string [USD, CAD]
gst	required, string decimal
gst_currency	required, string [USD, CAD]
line_items	Array of objects LineItem
shipments	Array of objects Shipment
shipping_address	object ShippingAddress
customer	object Customer
provided_external_id	string [ 1 .. 255 ] characters

Example:

LineItem

Key	Tags
uuid	required, string uuid
product	required, object (Product)
variant	required, object (Variant)
quantity	required, integer
price	required, string decimal, This is per individual item. This price does not change

Example:

Shipment

Key	Tags
uuid	required, string uuid
tracking_number	string
tracking_url	required, string uri
shipped_date	required, string datetime

Example:

Product

Key	Tags
uuid	required, string uuid
name	required, string [ 1 .. 255 ] characters
base_product	object (BaseProduct)

Example:

BaseProduct

This is inherited by all your Products.

Key	Tags
uuid	required, string uuid
name	required, string [ 1 .. 255 ] characters
image	required, string uri
categories	Array of strings

Example:

Variant

Key	Tags
uuid	required, string uuid
image	required, string uri
price	required, string decimal, The price for a variant can change. Reference LineItem for the actual price at the time of placing an order
price_currency	required, string [USD, CAD]
base_variant	object (BaseVariant)

Example:

BaseVariant

This is inherited by all your Variants.

Key	Tags
uuid	required, string uuid
options	Array of objects (VariantOption), includes (size, color, etc)
option_values	Array of strings

Example: