Orders

Introduction

Through the endpoints included in the Orders section, you will be able to:

• Retrieve all the orders

• Retrieve details about a specific order

• Create orders

• Accept orders

• Update orders' shipping address

---

Blueprints vs. Pre-configured products

There are two main ways to place an order through the API:

1. Using SKUs from Blueprints You provide the SKU and attach a custom print file. This is like sending us a blank T-shirt or canvas and telling us what to print on it — flexible and ideal for on-demand or user-generated content.

2. Using Pre-configured products In contrast, you can also order ready-made products that were created via our product configurator in the dashboard (see the products section of the docs).

   • These already have artwork/designs attached

   • No need to send a print file with the order — you just reference the pre-made product_sku

This distinction is important — blueprint-based SKUs are customizable templates, while Products are finalized and ready for sale. Both are valid paths depending on your business model and integration.

Attribute	Blueprint-based SKU	Product (from Configurator)
Artwork attached?	No – print file must be provided when ordering (either via URL or image_id from the Library)	Yes – artwork is embedded in the product definition
SKU Format	Plain (e.g., CVS0200201LWF2)	With artwork code (e.g., CVS0200201LWF2-APO12345678)
Created via	API programmatically	Dashboard Configurator
Best for	Personalized/unique orders with dynamic content	Selling pre-made or branded product collections
Order method	Use product_sku + artwork with URL or image_id via /orders	Use product_sku only — no need to re-send artwork

Endpoints

Get orders

get

This API endpoint retrieves a list of all orders

Authorizations

BasicAuth

AuthorizationstringRequired

Header parameters

AcceptstringOptional

Media type(s) that is/are acceptable for the response

Default: application/json

Responses

200

OK

application/json

401

Unauthorized

get

/orders

HTTPcURLJavaScriptPython

GET /api/v1/orders HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: */*

{
  "data": [
    {
      "order_id": "PPO12345678",
      "external_id": null,
      "country": "DE",
      "shipping_type": "Tracked",
      "is_test": false,
      "total_amount": 100,
      "created_at": "2025-01-01T00:00:00+00:00",
      "updated_at": "2025-01-01T00:00:00+00:00",
      "fulfilled_at": null,
      "status": "Draft"
    }
  ]
}

Show order

get

This API endpoint retrieves information about the order

Authorizations

BasicAuth

AuthorizationstringRequired

Path parameters

orderstringRequired

The ID of the order.

Header parameters

AcceptstringOptional

Media type(s) that is/are acceptable for the response

Default: application/json

Responses

200

OK

application/json

401

Unauthorized

get

/orders/{order}

HTTPcURLJavaScriptPython

GET /api/v1/orders/{order} HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: */*

{
  "data": {
    "order_id": "PPO12345678",
    "external_id": null,
    "status": "Draft",
    "shipping": {
      "email": null,
      "firstname": "John",
      "lastname": "Doe",
      "company": null,
      "street_primary": "275 Wyman St.",
      "street_secondary": null,
      "city": "BE",
      "postcode": "01234",
      "country": "DE",
      "telephone": "[phone]"
    },
    "shipping_type": "Tracked",
    "is_test": true,
    "total_amount": {
      "amount": 100,
      "currency": "EUR"
    },
    "sub_total": {
      "amount": 90,
      "currency": "EUR"
    },
    "shipping_total": {
      "amount": 10,
      "currency": "EUR"
    },
    "customs_shipping": {
      "amount": 0,
      "currency": "EUR"
    },
    "customs_costs": {
      "amount": 0,
      "currency": "EUR"
    },
    "created_at": "2023-01-01T00:00:00+00:00",
    "updated_at": "2023-01-01T11:00:00+00:00",
    "fulfilled_at": null,
    "packages": [],
    "items": [
      {
        "external_id": "1",
        "sku": "CVS0200201LWF2",
        "article": {
          "id": 1,
          "sku": "CVS0200201LWF2-APO12345678"
        },
        "description": "20x20 cm - White - 2 cm",
        "quantity": 1,
        "unit_cost": {
          "amount": 7,
          "currency": "EUR"
        },
        "taxes": {
          "amount": 10,
          "currency": "EUR"
        },
        "total_item": {
          "amount": 10,
          "currency": "EUR"
        },
        "metadata": null
      }
    ]
  }
}

Create order

post

Authorizations

BasicAuth

AuthorizationstringRequired

Header parameters

Acceptstring · enumRequired

Media type(s) that is/are acceptable for the response

Default: application/jsonPossible values:

Body

application/json

or

or

Responses

200

OK

application/json

401

Unauthorized

422

Unprocessable Entity

post

/orders

HTTPcURLJavaScriptPython

POST /api/v1/orders HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: application/json
Content-Type: application/json
Content-Length: 375

{
  "external_id": "",
  "shipping_type": "tracked",
  "is_test": true,
  "shipping": {
    "firstname": "Sophie",
    "lastname": "Muller",
    "email": "[email protected]",
    "street_primary": "101 Elm Road",
    "country": "DE",
    "city": "Berlin",
    "postcode": "10115",
    "customs_shipping": 2.99
  },
  "items": [
    {
      "quantity": 1,
      "product_sku": "CVS0200201LWF2",
      "file": {
        "front": {
          "url": "https://example.com/images/image.png"
        }
      }
    }
  ]
}

Create orderCreate order including billing address

{
  "order_id": "PPO12345678"
}

Accept order

put

Authorizations

BasicAuth

AuthorizationstringRequired

Path parameters

orderstringRequired

The ID of the order.

Header parameters

Acceptstring · enumRequired

Media type(s) that is/are acceptable for the response

Default: application/jsonPossible values:

Responses

200

OK

application/json

401

Unauthorized

put

/orders/{order}/accept

HTTPcURLJavaScriptPython

PUT /api/v1/orders/{order}/accept HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: application/json

{
  "message": "Order has been accepted"
}

Update order's address

put

Authorizations

BasicAuth

AuthorizationstringRequired

Path parameters

orderstringRequired

The ID of the order.

Header parameters

Acceptstring · enumRequired

Media type(s) that is/are acceptable for the response

Default: application/jsonPossible values:

Body

application/json

emailstring · emailOptional

telephonestringOptional

firstnamestringRequired

lastnamestringRequired

companystringOptional

street_primarystringRequired

street_secondarystringOptional

Responses

200

OK

application/json

401

Unauthorized

403

Forbidden

put

/orders/{order}/update-address

HTTPcURLJavaScriptPython

PUT /api/v1/orders/{order}/update-address HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: application/json
Content-Type: application/json
Content-Length: 193

{
  "email": "[email protected]",
  "telephone": "[phone]",
  "firstname": "Sophie",
  "lastname": "Muller",
  "company": "Example Company",
  "street_primary": "101 Elm Road",
  "street_secondary": "Apt 123"
}

{
  "message": "Address has been updated"
}

---

Parameters

Field	Type	Required	Description
external_id	string		Unique identifier for your orders
shipping_type	string		Shipping type — currently, only tracked shipping is supported.
is_test	boolean		When value is set to true, then the order will be created as a test order, it will not be produced nor shipped
shipping	object		Contains the address and required information about end customer
shipping.email	string		Customer's email address
shipping.firstname	string		Customer's first name
shipping.lastname	string		Customer's last name
shipping.company	string		Customer's company name, used when the end customer is ordering on behalf of a company
shipping.street_primary	string		Customer's street address
shipping.street_secondary	string		Customer's additional address
shipping.city	string		Customer's city
shipping.postcode	string		Customer's postcode
shipping.country	string		Customer's country, ISO 3166-1 alpha-2 standard
shipping.region	string		Customer's region. ❗ Required for US and CA.
shipping.telephone	string		Customer's phone number
shipping.customs_shipping	number		This value is used to print the shipping costs shown on the Customs Declaration
billing	object		Override the default billing address ❗ This is required for companies without a billing address
billing.firstname	string		Customer's first name
billing.lastname	string		Customer's last name
billing.company	string		Customer's company
billing.vat	string		Customer's VAT
billing.street_primary	string		Customer's street address
billing.street_secondary	string		Customer's additional address
billing.country	string		Customer's country
billing.region	string		Customer's region ❗Required for US and CA.
billing.city	string		Customer's city
billing.postcode	string		Customer's postcode
items	array		An array with on or more items
items.external_id	string		Unique identifier for your items
items.quantity	integer		The number of copies to produce of this particular item
items.customs_value	number		This value is used to print the shipping costs shown on the Customs Declaration
items.product_sku	string		The product SKU which may or may not include the associated artwork.
items.image_id	string		Id of an image from your library ❗Required when items.product_sku does not include artwork or items.file.front.url is not provided
items.file	object		❗Required when items.product_sku does not include artwork or items.image_id is not provided
items.file.front.url	string		URL of the print file