Documentation

Explore our guides and examples to integrate OrderMerch

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

pagination

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

KeyTagsDescription
line_itemsrequired, non-emptyArray of objects (PlacedLineItem)
shipping_addressrequiredobject (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.

KeyTags
namestring
alpha_two_codestring
alpha_three_codestring
numeric_codestring
requires_postal_codeboolean

Request:

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

Responses:

HTTP 200 OK

pagination

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.

StatusDescription
ShippingThe order has sent out a shipment. Other items still need to be shipped.
CompletedThe order has sent out all shipments. The order is now considered complete.
CancelledThe order was cancelled. This order will not be updated anymore.
ProblemThere 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

KeyTags
first_namerequired, string [ 1 .. 35 ] characters
last_namerequired, string [ 1 .. 35 ] characters
emailrequired, string email [ 1 .. 254 ] characters
addressrequired, string [ 1 .. 50 ] characters
address_twostring [ 1 .. 50 ] characters
cityrequired, string [ 1 .. 32 ] characters
countryrequired, string [ 1 .. 56 ] characters, alpha_three_code from Country
state_or_provincestring [ 1 .. 255 ] characters, name from Subdivision, required if a country has subdivisions
zip_or_postal_codestring [ 1 .. 32 ] characters, required if a country has the field requires_postal_code
companystring [ 1 .. 35 ] characters
phone_numberrecommended, required for some countries, string [ 1 .. 18 ] characters

Example:


Country

KeyTags
namerequired, string [ 1 .. 255 ] characters
alpha_two_coderequired, string [ 1 .. 2 ] characters
alpha_three_coderequired, string [ 1 .. 3 ] characters
numeric_coderequired, string [ 1 .. 3 ] characters
requires_postal_coderequired, boolean
subdivisionsrequired, Array of objects Subdivision

Example:


Subdivision

KeyTags
namerequired, string [ 1 .. 255 ] characters
coderequired, string [ 1 .. 6 ] characters
isostring
categorystring

Example:


PlacedLineItem

KeyTags
product_uuidrequired, string uuid
variant_uuidrequired, string uuid
quantityinteger, default 1

Example:


Order

KeyTags
uuidrequired, string uuid
created_atrequired, string datetime
updated_atrequired, string datetime
is_activerequired, boolean
statusrequired, string [Pending, In Progress, Completed, Shipping, Cancelled, Problem]
totalrequired, string decimal
subtotalrequired, string decimal
subtotal_currencyrequired, string [USD, CAD]
shippingrequired, string decimal
shipping_currencyrequired, string [USD, CAD]
taxrequired, string decimal
tax_currencyrequired, string [USD, CAD]
gstrequired, string decimal
gst_currencyrequired, string [USD, CAD]
line_itemsArray of objects LineItem
shipmentsArray of objects Shipment
shipping_addressobject ShippingAddress
customerobject Customer
provided_external_idstring [ 1 .. 255 ] characters

Example:


LineItem

KeyTags
uuidrequired, string uuid
productrequired, object (Product)
variantrequired, object (Variant)
quantityrequired, integer
pricerequired, string decimal, This is per individual item. This price does not change

Example:


Shipment

KeyTags
uuidrequired, string uuid
tracking_numberstring
tracking_urlrequired, string uri
shipped_daterequired, string datetime

Example:


Product

KeyTags
uuidrequired, string uuid
namerequired, string [ 1 .. 255 ] characters
base_productobject (BaseProduct)

Example:


BaseProduct

This is inherited by all your Products.

KeyTags
uuidrequired, string uuid
namerequired, string [ 1 .. 255 ] characters
imagerequired, string uri
categoriesArray of strings

Example:


Variant

KeyTags
uuidrequired, string uuid
imagerequired, string uri
pricerequired, string decimal, The price for a variant can change. Reference LineItem for the actual price at the time of placing an order
price_currencyrequired, string [USD, CAD]
base_variantobject (BaseVariant)

Example:


BaseVariant

This is inherited by all your Variants.

KeyTags
uuidrequired, string uuid
optionsArray of objects (VariantOption), includes (size, color, etc)
option_valuesArray of strings

Example:

OrderMerch logoOrderMerch

© 2022 OrderMerch - All rights reserved