Orders

Introduction

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

• Retrieve information about the orders

• Create new orders

• Retrieve information about a specific order

• Cancel orders

Endpoints

Orders

Show orders

get

This API endpoint retrieves information about the orders.

Authorizations

basicAuth

AuthorizationstringRequired

Responses

200

Request completed successfully.

application/json

401

Unauthorized

get

/orders

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "id": "PPO21694395T",
      "external_id": "",
      "is_test": true,
      "shipping_method": {
        "code": "DHL",
        "name": "DHL"
      },
      "status": "DRAFT",
      "status_label": "Draft",
      "created_at": "2023-01-01T00:00:00.000000Z",
      "updated_at": "2023-01-01T00:00:00.000000Z",
      "shipments": [],
      "items": [
        {
          "id": 3399,
          "external_id": null,
          "variant_id": 3,
          "name": "40x30 cm",
          "quantity": 1,
          "price": 24.92,
          "price_details": {
            "currency": "EUR",
            "formatted": "24.92 €",
            "in_subunit": "2492"
          },
          "file": "https://dummyimage.com/4000x3000/fff/000&text=api.merchone.com",
          "options": [
            {
              "id": 1,
              "name": "Canvas border",
              "value": {
                "id": 3,
                "name": "Stretched"
              }
            }
          ]
        }
      ],
      "totals": {
        "subtotal_amount": 24.92,
        "subtotal_amount_details": {
          "currency": "EUR",
          "formatted": "24.92 €",
          "in_subunit": "2492"
        },
        "shipping_amount": 3.34,
        "shipping_amount_details": {
          "currency": "EUR",
          "formatted": "3.34 €",
          "in_subunit": "334"
        },
        "total_amount": 28.26,
        "total_amount_details": {
          "currency": "EUR",
          "formatted": "28.26 €",
          "in_subunit": "2826"
        },
        "customs_shipping_costs": 5.99,
        "customs_shipping_costs_details": {
          "currency": "EUR",
          "formatted": "5.99 €",
          "in_subunit": "599"
        }
      },
      "meta": {
        "pagination": {
          "total": 10,
          "count": 10,
          "per_page": 1,
          "current_page": 1,
          "total_pages": 1,
          "links": {
            "previous": "/api/beta/orders?page=1",
            "next": "/api/beta/orders?page=3"
          }
        }
      }
    }
  ]
}

Create order

Create an order

post

This API endpoint creates an order and returns it.

Authorizations

basicAuth

AuthorizationstringRequired

Body

application/json

external_idstringOptional

is_testbooleanOptionalExample: true

shipping_methodstringOptionalExample: DHL

customs_shipping_costsnumberOptional

Used to print the customs duty value of the order item and shipping costs shown on the customs duty invoice

Example: 5.99

Responses

200

Request completed successfully.

application/json

401

Unauthorized

422

Unprocessable entity

application/json

post

/orders

HTTPcURLJavaScriptPython

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

{
  "external_id": "",
  "is_test": true,
  "shipping_method": "DHL",
  "customs_shipping_costs": 5.99,
  "shipping": {
    "email": "[email protected]",
    "firstname": "John",
    "lastname": "Doe",
    "company": "merchOne GmbH",
    "street_primary": "Hohenzollernring 25",
    "street_secondary": "Apt 18",
    "city": "Cologne",
    "postcode": "50672",
    "country_id": 276,
    "region_id": null,
    "telephone": "[phone]"
  },
  "items": [
    {
      "external_id": null,
      "quantity": 1,
      "variant_code": "DIGI-40X30-1",
      "customs_value": 19.99,
      "file": "https://dummyimage.com/4000x3000/fff/000&text=api.merchone.com",
      "options": {
        "1": 3,
        "Stretcher frame": "2 cm"
      }
    }
  ]
}

{
  "data": {
    "id": "PPO21694395T",
    "external_id": "",
    "is_test": true,
    "shipping_method": {
      "code": "DHL",
      "name": "DHL"
    },
    "status": "DRAFT",
    "status_label": "Draft",
    "created_at": "2023-01-01T00:00:00.000000Z",
    "updated_at": "2023-01-01T00:00:00.000000Z",
    "shipments": [],
    "items": [
      {
        "id": 3399,
        "external_id": null,
        "variant_id": 3,
        "name": "40x30 cm",
        "quantity": 1,
        "price": 24.92,
        "price_details": {
          "currency": "EUR",
          "formatted": "24.92 €",
          "in_subunit": "2492"
        },
        "file": "https://dummyimage.com/4000x3000/fff/000&text=api.merchone.com",
        "options": [
          {
            "id": 1,
            "name": "Canvas border",
            "value": {
              "id": 3,
              "name": "Stretched"
            }
          }
        ]
      }
    ],
    "totals": {
      "subtotal_amount": 24.92,
      "subtotal_amount_details": {
        "currency": "EUR",
        "formatted": "24.92 €",
        "in_subunit": "2492"
      },
      "shipping_amount": 3.34,
      "shipping_amount_details": {
        "currency": "EUR",
        "formatted": "3.34 €",
        "in_subunit": "334"
      },
      "total_amount": 28.26,
      "total_amount_details": {
        "currency": "EUR",
        "formatted": "28.26 €",
        "in_subunit": "2826"
      },
      "customs_shipping_costs": 5.99,
      "customs_shipping_costs_details": {
        "currency": "EUR",
        "formatted": "5.99 €",
        "in_subunit": "599"
      }
    }
  }
}

Get order

Show an order

get

This API endpoint retrieves information about the specific order.

Authorizations

basicAuth

AuthorizationstringRequired

Path parameters

order_idstringRequired

order_id or @external_id

Responses

200

Request completed successfully.

application/json

401

Unauthorized

422

Unprocessable entity

application/json

get

/orders/{order_id}

HTTPcURLJavaScriptPython

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

{
  "data": {
    "id": "PPO21694395T",
    "external_id": "",
    "is_test": true,
    "shipping_method": {
      "code": "DHL",
      "name": "DHL"
    },
    "status": "DRAFT",
    "status_label": "Draft",
    "created_at": "2023-01-01T00:00:00.000000Z",
    "updated_at": "2023-01-01T00:00:00.000000Z",
    "shipments": [],
    "items": [
      {
        "id": 3399,
        "external_id": null,
        "variant_id": 3,
        "name": "40x30 cm",
        "quantity": 1,
        "price": 24.92,
        "price_details": {
          "currency": "EUR",
          "formatted": "24.92 €",
          "in_subunit": "2492"
        },
        "file": "https://dummyimage.com/4000x3000/fff/000&text=api.merchone.com",
        "options": [
          {
            "id": 1,
            "name": "Canvas border",
            "value": {
              "id": 3,
              "name": "Stretched"
            }
          }
        ]
      }
    ],
    "totals": {
      "subtotal_amount": 24.92,
      "subtotal_amount_details": {
        "currency": "EUR",
        "formatted": "24.92 €",
        "in_subunit": "2492"
      },
      "shipping_amount": 3.34,
      "shipping_amount_details": {
        "currency": "EUR",
        "formatted": "3.34 €",
        "in_subunit": "334"
      },
      "total_amount": 28.26,
      "total_amount_details": {
        "currency": "EUR",
        "formatted": "28.26 €",
        "in_subunit": "2826"
      },
      "customs_shipping_costs": 5.99,
      "customs_shipping_costs_details": {
        "currency": "EUR",
        "formatted": "5.99 €",
        "in_subunit": "599"
      }
    }
  }
}

Delete order

Cancel an order

delete

This API endpoint cancels a specific order.

Authorizations

basicAuth

AuthorizationstringRequired

Path parameters

order_idstringRequired

ID of the order

Responses

204

Order successfully canceled

401

Unauthorized

422

Unprocessable entity

application/json

delete

/orders/{order_id}

HTTPcURLJavaScriptPython

DELETE /api/beta/orders/{order_id} HTTP/1.1
Host: api.merchone.com
Authorization: Basic username:password
Accept: */*

No content

Order status

Order statuses are used to track the progress of an order and provide information about its current state. You can find a more detailed list below:

Status	Description
Draft	Order has been submitted but not yet confirmed.
Accepted	Order has been confirmed and is being prepared for shipment.
Fulfilled	Order has been completed and the product(s) is ready to be shipped.
Generated	Order has been generated
In Progress	Order is in progress
Cancelled	Order has been cancelled by the customer or admin.
Refunded	Order has been refunded to the customer.
Partial Refund	Order has been partially refunded to the customer.
Pending	Order has been placed by the customer and is waiting for payment to be completed.
Error	Something went wrong during the processing of the order.

Parameters

Key	Description
external_id (optional)	Unique identifier for your orders
is_test (optional)	When value is set to true, the order will be created as a TEST Order (PPOXXXXXXXXT) and will NOT be produced or shipped. When the store is in sandbox mode, all orders are created as TEST Orders regardless of the value sent in this field. shipping_method must be valid for the shipping country and the items listed in the order. See the guideline above: Guide to calculate shipping rate/method to find out which shipping methods are valid for the given combination of values. Failure to choose a correct shipping method will result in an error.
shipping_type (optional)	Must be used when shipping_method is unknown or doesn't matter which carrier is used for shipping. The values can be either UNTRACKED or TRACKED as listed under GET api/beta/shipping/types endpoint. If both are provided then shipping_method has higher priority.
customs_shipping_costs (optional)	This value is used to print the shipping costs shown on the Customs Declaration Papers when a shipment is sent to NON-EU countries. The value to place here is the retail shipping price you charged your end customer. It is always used in combination with items' customs_value.
shipping	Object contains the address and required information about end customer. There is no need of billing address.
shipping.email (optional)	End customer's email address.
shipping.firstname	End customer's first name.
shipping.lastname	End customer's last name.
shipping.company (optional)	End customer's company name when the end customer is ordering on behalf of a company.
shipping.street_primary	End customer's street name and house number.
shipping.street_secondary (optional)	Additional address.
shipping.city	End customer's city name.
shipping.postcode	End customer's postal/zip code.
shipping.country_id	End customer's country - ISO 3166-1 numeric-3 OR country_code - ISO 3166-1 alpha-2 standards.
shipping.region_id (required for US and Canada)	End customer's state name - ANSI INCITS 38:2009 digit-2. It should be used in combination with country_id. The list of regions/states can be checked at a/api/beta/regions/{country_id}.
shipping.region_code	It should be used in combination with country_code - ANSI INCITS 38:2009 alpha-2. The list of regions/states can be checked at /api/beta/regions/{country_id}.
shipping.telephone (optional)	End customer's phone number - used in case of any problems during delivery by the shipment provider.
items	An array with one or more item objects.
items.external_id (optional)	Unique identifier for your items.
items.customs_value (optional)	This value will be used to print the net item cost shown on the Customs Declaration Papers when a shipment is sent to NON-EU countries. The value to place here is the net retail selling price you charged your end customer. It is always used in combination with order's customs_shipping_costs.
items.quantity	The number of copies to produce of this particular item.
items.variant_code	The identifier of which product variant this item is, for example "DIGI-40X30-1" is for a 40x30 cm canvas. See the guideline above: Guide to get a product variant to find out which code/id to use.
items.variant_id	can be used alternatively in place of variant_code but only ONE of them should be used, failing to do so will result in error or create wrong orders. For example variant id "3" identifies the same 40x30 cm canvas as variant code "DIGI-40X30-1" does. See the guideline above: Guide to get a product variant to find out which code/id to use.
items.article_sku	Can be used alternatively instead of variant_code or variant_id but only ONE of them should be used, failing to do so will result with an error or create wrong orders. For example article_sku "CVS0400301F2SW-APOXXXXXXXX" identifies the same 40x30cm canvas with 2cm Border thickness and pre-uploaded image(APOXXXXXXXX). article_sku can be found in your store product list on the edit product page. article_sku is not a common identifier, it is strictly linked to the store where it was created.
items.file	The URL to the print file for this particular item. See more detailed about the file format, resolution and aspect ratio in the "Print Files" section below.
items.options	A list with one or more options set for a product variant. Some product variant have required options, for example all canvas variants have 2 required options ("Canvas border" and "Stretcher frame"). The key and value of an option can either be their ids or their names. For example, the option "Canvas border" option can be added like'Canvas border':'Stretched' (using names) or can be alternatively added "1" : 3 (using ids). The names for keys and values are case-sensitive. The list of options for every variant can be checked at guideline above: Guide to get a product variant and details.