Appearance

Orders Endpoint ​

The Orders Endpoint is a key component of the Merchrocket API. It allows you to create, update and confirm new orders for fulfilment.

What the order endpoint can do ​

Using the Merchrocket API, you can perform the following actions on order endpoints:

Create orders ​

An example of creating a simple order using the Merchrocket API can be found here, while examples for reprint orders are available here.

The following documentation explains each point in more detail.

Order life cycle and statuses ​

Every order passes through different stages during its processing. Please refer to our workflow documentation for a detailed explanation of these processes and statuses.

External IDs ​

With the External ID attribute, Merchrocket orders are linked to the order ID of your system so that no additional data storage is required on your side. The external ID can be up to 63 characters long and can contain letters, numbers, hyphens and underscores. However, it is recommended to use simple, unique identifiers.

Simply add the externalId attribute when you create the order. You can later access the order via the API by referencing either the order ID or the external ID (preceded by an @ symbol).

console
# Call to retrieve an order with the Merchrocket ID
GET /api/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6  

# Call to retrieve an order with your External ID
GET /api/orders/@YOW-7792796022

Actions ​

Additional actions can be taken during order creation. In this example, a reprint can be requested if the delivered item does not meet expectations. This is currently the only action available.

console
{
  "actions": [
    {
      "type": "reprint",
      "source": "@TCS-5442223218"
    }
  ],

For a complete reprint order example, click here.

Associations ​

When orders are linked, the API returns association data in the response. For example, in a reprint scenario, the API will return information about both the original order (source) and the reprint order (linked). Each order is identified by its internal ID and external ID. The association also includes the type of relationship ("reprint" or "refund") and the timestamp when it was created.

console
# Example: Reprint association
"associations": [
    {
        "type": "reprint",
        "createdAt": "2024-12-11T09:31:34+00:00",
        "source": {
            "@id": "/api/orders/01920e66-e717-7f1a-9223-1911cd94d198",
            "@type": "Order",
            "id": "01920e66-e717-7f1a-9223-1911cd94d198",
            "externalId": "SOURCE-5442223218"
        },
        "linked": [
            {
                "@id": "/api/orders/0193b50f-391f-73c3-b654-192a3c861d97",
                "@type": "Order",
                "id": "0193b50f-391f-73c3-b654-192a3c861d97",
                "externalId": "LINKED-4336994326"
            }
        ]
    }
]

# Example: Refund association
"associations": [
    {
        "type": "refund",
        "createdAt": "2024-12-11T09:31:34+00:00",
    }
]

Specifying product ​

When creating an order, you must specify a product by Variant ID for each order item.

json
{
  ...
  "orderItems": [
    {
      ...
      "variantId": "590f1af7-75f6-46c8-bab3-60b109a66371",
      ...
    }
  ]
}

You can use our Catalog API to retrieve these variant IDs. The variants and their IDs are listed for each product. Variant IDs are also visible in the product catalogue on our website.

Adding print file ​

A print file must be specified by URL for each order item. This URL must be publicly accessible to the Merchrocket system.

json
  ...
  "orderItems": [
    {
      ...
      "placements": [
        {
          ...
          "layers": [
            {
              "url": "https://www.example.org/example.pdf",
              "type": "file",
              ...      
            }
          ]
          ...
        }
      ]
    }
  ]
}

Specifying file position ​

A file position must be specified for each order item.

Important ​

  • Each placement has specific dimensions. We currently only support one file per placement. This file must have the same dimensions as the placement. For this reason, the placement must always be top left (0,0).

Steps ​

  1. Get the dimensions using the Catalog API
json
...
{
  "hydra:member": [
    {
      ...,
      "variants": [
        {
          ...,
          "placements": [
            {
              "area": {
                "width": 218,
                "height": 72,
                "section": {
                  "top": 0,
                  "right": 0,
                  "bottom": 0,
                  "left": 0
                }
              },
              "visibleArea": {
                "width": 218,
                "height": 72,
                "top": 0,
                "left": 0
              }
            }
          ],
          ...
        }
      ],
      ...
    }
  ],
  ...
}
  1. Specify the position according to the specifications in our product catalogue
json
{
  ...
  "orderItems": [
    {
      ...
      "placements": [
        {
          ...
          "layers": [
            {
              ...
              "position": {
                "top": 0,
                "left": 0,
                "width": 218,
                "height": 72
              }
            }
          ],
          ...
        }
      ]
    }
  ]
}

Specifying the product options ​

Some of our products require product options when ordering. Without these option(s) we cannot produce the item. Whether and which options a product has and where you can get the possible values can be found in a detailed explanation here.

json
  ...
  "orderItems": [
    {
      ...
      "options": [
        { "id": "", "value": ""}
      ]
      ...  
    }
  ]
}

API-Properties ​

externalId ​

  • Type: String
  • Description: The external ID, which must be unique, can be freely assigned and may only contain letters, numbers, hyphens, and underscores.
  • Example: YOW-7792796022

shipping ​

  • Type: String
  • Description: The shipping method for the order. Possible values include:
    • STANDARD: Standard shipping
    • DHL_EXPRESS: DHL Express shipping
  • Example: STANDARD

recipient ​

An object that contains the shipping address for the order.

  • Fields:

    • name

      • Type: String
      • Description: The name of the recipient.
      • Example: Alex Johnson

    • company

      • Type: String
      • Description: The name of the recipient's company (optional).
      • Example: Johnson Enterprises

    • address1

      • Type: String
      • Description: The first line of the address.
      • Example: 123 Main Street

    • address2

      • Type: String
      • Description: The second line of the address (optional).
      • Example: Suite 100

    • city

      • Type: String
      • Description: The city of the recipient.
      • Example: San Francisco

    • stateCode

      • Type: String
      • Description: The state or province code.
      • Example: CA

    • stateName

      • Type: String
      • Description: The name of the state or province.
      • Example: California

    • countryCode

      • Type: String
      • Description: The country code in ISO 3166-1 alpha-2 format.
      • Example: US

    • countryName

      • Type: String
      • Description: The name of the country.
      • Example: United States

    • zip

      • Type: String
      • Description: The postal code.
      • Example: 94102

    • phone

      • Type: String
      • Description: The recipient's phone number.
      • Example: 555-123-4567

    • email

    • taxNumber

      • Type: String
      • Description: The recipient's tax identification number.
      • Example: 654321987

orderItems ​

An array of objects describing the items in the order.

  • Fields for each item object:

    • externalId

      • Type: String
      • Description: A unique identifier for the item, which can be freely assigned.
      • Example: PAY-4627172881

    • quantity

      • Type: Integer
      • Description: The quantity of the ordered item.
      • Example: 1

    • name

      • Type: String
      • Description: The name of the item, which can be freely assigned.
      • Example: Heart-Shaped Mug

    • retailPrice

      • Type: String
      • Description: Your retail price of the item in "currency price" format.
      • Example: 19.90

    • variantId

      • Type: String
      • Description: A unique identifier for the item's variant.
      • Example: 590f1af7-75f6-46c8-bab3-60b109a66371

    • placements

      • Type: Array of objects

      • Description: Information about the design or print placement on the item.

      • Fields for each placement object:

        • type

          • Type: String
          • Description: The type of placement (e.g., "front" for the front side).
          • Example: front

        • technique

          • Type: String
          • Description: The printing technique (e.g., "direct_print").
          • Example: direct_print

        • layers

          • Type: Array of objects

          • Description: Layers used for the design.

          • Fields for each layer object:

            • url

            • type

              • Type: String
              • Description: The type of file ("file").
              • Example: file

            • position

              • Type: Object

              • Description: Position and size of the design on the item.

              • Fields for the position object:

                • top

                  • Type: Number
                  • Description: The top edge of the design in pixels.
                  • Example: 0

                • left

                  • Type: Number
                  • Description: The left edge of the design in pixels.
                  • Example: 0

                • width

                  • Type: Number
                  • Description: The width of the design in pixels.
                  • Example: 218

                • height

                  • Type: Number
                  • Description: The height of the design in pixels.
                  • Example: 98.5

        • placementOptions

          • Type: Array of objects

          • Description: Options for the placement of the design.

          • Fields for each placement option object:

            • name

              • Type: String
              • Description: Name of the placement option (e.g., "unlimited_color").
              • Example: unlimited_color

            • value

              • Type: Boolean
              • Description: Value of the placement option (e.g., true for unlimited colors).
              • Example: true

    • options

      • Type: Array of objects
      • Description: Product-options for the options of the product variant.
      • Fields for each placement option object:

        • id

          • Type: String
          • Description: Id of the product option
          • Example: color_scheme

        • value

          • Type: String
          • Description: Value of the product option
          • Example: light_blue