# Overview > **Note:** This documentation focuses on using the merchOne API. For guidance on registering for a merchOne account and using the merchOne application, please visit the [merchOne Knowledge Base](https://service.merchone.com/knowledge). To explore the products and services offered by merchOne, please visit the [merchOne website](https://merchone.com/). The merchOne API enables access to the merchOne services through multiple methods, and this documentation provides comprehensive descriptions, including code examples, to assist in the creation of products and fulfillment of orders through the merchOne API.
## **API Guidelines** All integrations must adhere to the merchOne Terms and merchOne API Terms, as outlined on the terms of service page: * ## **Limitations** * API limit: merchOne engineering closely monitors usage of the public APIs to ensure a quality experience for users of the merchOne platform. To maintain performance, a limit of *60 API calls per minute* has been set at the account level.
* Maximum items per order: The merchOne API is limited to *99 items per order*, meaning that a single order can include a maximum of 99 items.
* Maximum file size for image uploads: The merchOne API has a 40MB limit for image file size, so the images uploaded to the API must be smaller than 40MB. \ Integrations using the merchOne API for mockup generation have additional daily limits. The mockup generation endpoints have a limit of 100 requests per minute. If your application requires frequent use of the mockup generation function, please contact the support team at merchone.com for further assistance. \ \ Additionally, the preview integration is a standalone offering, and customers interested in accessing it should reach out to the support team for more information. \ **Glossary** ------------
TermDescription
Blueprintrefers to all products (before customization) offered on our platform, including but not limited to wall decoration, clothing, accessories.
Blueprint accessoriesRefers to items that enhance the use of a blueprint such as frames, hanger set, etc
Blueprint variantRefers to a specific version of a blueprint that differs in some way from other versions of the same blueprint. It generally refers to a combination of size, features, options and accessories.
ProductRefers to a combination of Blueprint variants and content created by the merchant
Product previewRefers to visual representations of Users’ Products created through our Service.
StoreIn a merchOne account, the order placement happen within individual shops. An account can have multiple shops, each with its own unique connection to different sales channels and independent sets of products and orders. A shop is usually connected with one specific merchOne factory, from where orders will be fulfilled.
Store statusThe distinction between sandbox and live environments refers to the stage of API integration testing. Sandbox is a testing environment for developers to experiment and test API configurations, while live environment is for actual transactions and order fulfillment.

Orders in sandbox are not fulfilled, while orders in live environment are produced and shipped to customers.
# REST API > **Note:** This page provides an overview of the merchOne REST API and its available integration features. For guidance on registering for a merchOne account and using the merchOne application, please visit the [merchOne Knowledge Base](https://service.merchone.com/knowledge). To explore the products and services available from merchOne, please visit [merchOne.com](https://merchone.com/). ## REST API The merchOne REST API enables seamless integration and automation of image manipulation and product creation within external software systems. Some of the features that can be achieved using the merchOne API include: 1. [**Order Management**](/api-reference/api-beta/orders): The API allows for the management of orders, including the ability to create new orders, retrieve order details, and cancel orders (if the order has not yet been accepted by the system).
2. [**Catalog**](/api-reference/api-beta/catalog): The API allows for retrieving blueprints and blueprints variants that are associated with a specific store.
3. [**Shipping**](/api-reference/api-beta/shipping): The API allows retrieval of countries, regions, shipping types, shipping methods, and calculation of shipping costs. ## Web hooks Webhooks enable real-time notifications of shipping events. Typically, only the shipped status is reported. However, customers who wish to track intermediate stages such as pickup or transit can request activation of these notifications by contacting customer support.\ \ More information about webhooks can be found [here ](broken://pages/JFcdi8H7FnePX2zuwJeB) ## Libraries The following libraries have been made accessible to accelerate the integration process for developers: PHP Laravel JS/Node.js # API reference > **Note:** This page explains how to create a store and retrieve the credentials required for API integration. For detailed guidance on registering for a merchOne account, managing stores, and using the merchOne application, please visit the [merchOne Knowledge Base](https://service.merchone.com/knowledge). To explore merchOne’s available products and services, please visit [merchOne.com](https://merchone.com/). Getting started with integration is a breeze! The first step is to create a store and get your store credentials for a secure connection. Simply go to the "Stores" section from the left-hand menu and click the "Create" button in the custom integration box. You'll then be asked to provide a few details such as: * The name of your store * The store's URL * Your preferred printing location (either Europe or North America) When it comes to your printing location, keep in mind that it affects the customers you can serve. If you choose Cologne, you'll be able to reach European customers as well as some extra-European destinations. And if you choose Miami, you'll be able to serve customers in the US, Canada, and Puerto Rico.
By default, stores are set in sandbox mode, meaning that all incoming orders will not be fulfilled. Once you've created your store, you can easily access your store credentials from the settings page.
**Type:** `Basic`\ **User:** `Store's API user`\ **Password:** `Store's API key`\ **Header format:** `Authorization: Basic base64_encode(user:password)`
# API Beta {% hint style="danger" %} **Important:** Our API Beta will be deprecated soon, please switch your integrations to [**API V1**](/api-reference/api-v1) to ensure uninterrupted service. {% endhint %} # Catalog ## Introduction Through the endpoints included in the Catalog section, you will be able to: * Retrieve all the available products * Get information about the products' variants * Retrieve information about the options available for a specific store (corresponding to a determined printing/fulfillment location i.e. North America or Europe) ## Endpoints ### Products ## Show products > This API endpoint retrieves a list of all available products. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/products":{"get":{"summary":"Show products","description":"This API endpoint retrieves a list of all available products.","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"An array of product objects containing the following attributes","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier for the product."},"name":{"type":"string","description":"The name of the product."},"variants":{"type":"integer","description":"The number of variants available for the product."},"sku":{"type":"string","description":"The SKU (Stock-Keeping Unit) code for the product."},"dpi":{"type":"integer","description":"The minimum DPI (dots per inch) for the product."},"type":{"type":"string","description":"The type of product."},"images":{"type":"array","description":"An array of image objects containing the following attributes.","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier for the image."},"original":{"type":"string","description":"The URL of the original image."},"thumb":{"type":"string","description":"The URL of the thumbnail image."}}}}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ### Product's variants ## Show product's variants > This API endpoint retrieves a list of all available product's variants. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}}},"paths":{"/products/{product_id}":{"get":{"summary":"Show product's variants","description":"This API endpoint retrieves a list of all available product's variants.","parameters":[{"name":"product_id","in":"path","description":"ID of product to return","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"variant_id":{"type":"integer"},"variant_code":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"printfile":{"type":"object"},"price":{"type":"number"},"price_details":{"type":"object"},"shipping_countries":{"type":"array","items":{"type":"integer"}},"options":{"type":"object"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ### Variant's options ## Show variant's options > This API endpoint retrieves a list of all available variant's options.\
\
The \`variant\_id\` can be checked at \`/api/beta/products/{product\_id}\` ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}}},"paths":{"/variants/{variant_id}":{"get":{"summary":"Show variant's options","description":"This API endpoint retrieves a list of all available variant's options.

The `variant_id` can be checked at `/api/beta/products/{product_id}`","parameters":[{"name":"variant_id","in":"path","description":"ID of the variant","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"code":{"type":"string"},"variant_id":{"type":"integer"},"variant_code":{"type":"string"},"sku":{"type":"string"},"name":{"type":"string"},"printfile":{"type":"object"},"price":{"type":"number"},"price_details":{"type":"object"},"shipping_countries":{"type":"array","items":{"type":"integer"}},"options":{"type":"object"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ### SKU's variant options ## Show SKU's variant options > This API endpoint retrieves a list of all available SKU's variant options.\
\
The \`variant\_id\` can be checked at \`/api/beta/products/{product\_id}\` ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}}},"paths":{"/variants/{variant_id}/combinations":{"get":{"summary":"Show SKU's variant options","description":"This API endpoint retrieves a list of all available SKU's variant options.

The `variant_id` can be checked at `/api/beta/products/{product_id}`","parameters":[{"name":"variant_id","in":"path","description":"ID of variant to return","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"integer"},"price_details":{"type":"object"},"options":{"type":"array"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` # 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 > This API endpoint retrieves information about the orders. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"SingleOrder":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the order."},"external_id":{"type":"string","description":"An optional external unique identifier for the order"},"is_test":{"type":"boolean","description":"A boolean indicating whether the order is a test order"},"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"status":{"type":"string","description":"The status of the order."},"status_label":{"type":"string","description":"A human-readable label for the order status."},"created_at":{"type":"string","description":"Creation date and timezone of the order."},"updated_at":{"type":"string","description":"The last update date and timezone of the order."},"shipments":{"type":"array","description":"An array of objects containing details about the shipment","items":{"properties":{"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"shipped_at":{"type":"string"},"items":{"type":"array","items":{"properties":{"item_id":{"type":"integer"},"item_external_id":{"type":"string"},"quantity":{"type":"integer"}}}}}}},"items":{"type":"array","description":"An array of objects representing the items in the order.","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier for the item."},"external_id":{"type":"string","description":"An optional external unique identifier for the item."},"variant_id":{"type":"string","description":"The unique identifier for the item variant."},"name":{"type":"string","description":"The name of the item."},"quantity":{"type":"integer","description":"The quantity of the item in the order."},"price":{"type":"number","description":"The price of the item."},"price_details":{"type":"object","description":"An object containing details about the price of the item.","properties":{"currency":{"type":"string","description":"The currency of the price."},"formatted":{"type":"string","description":"A human-readable representation of the price."},"in_subunit":{"type":"integer","description":"The price in the smallest unit of the currency"}}},"file":{"type":"string","description":"The URL of the image associated with the item"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"value":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}}}}},"totals":{"type":"object","properties":{"subtotal_amount":{"type":"number"},"subtotal_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"shipping_amount":{"type":"number"},"shipping_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"total_amount":{"type":"number"},"total_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"customs_shipping_costs":{"type":"number"},"customs_shipping_costs_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}}}}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/orders":{"get":{"summary":"Show orders","description":"This API endpoint retrieves information about the orders.","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SingleOrder"},{"properties":{"meta":{"type":"object","properties":{"pagination":{"type":"object","properties":{"total":{"type":"integer"},"count":{"type":"integer"},"per_page":{"type":"integer"},"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"links":{"type":"object","properties":{"previous":{"type":"string"},"next":{"type":"string"}}}}}}}}}]}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ### Create order ## Create an order > This API endpoint creates an order and returns it. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"OrderPost":{"type":"object","properties":{"external_id":{"type":"string"},"is_test":{"type":"boolean"},"shipping_method":{"type":"string"},"customs_shipping_costs":{"type":"number","description":"Used to print the customs duty value of the order item and shipping costs shown on the customs duty invoice"},"shipping":{"type":"object","required":["firstname","lastname","country_id","city","postcode","street_primary"],"properties":{"email":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"company":{"type":"string"},"street_primary":{"type":"string"},"street_secondary":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"country_id":{"type":"integer"},"region_id":{"type":"integer"},"telephone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_code","file","quantity"],"properties":{"external_id":{"type":"string"},"quantity":{"type":"integer"},"variant_code":{"type":"string"},"customs_value":{"type":"number","description":"Used to print the customs duty value of the order item and shipping costs shown on the customs duty invoice"},"file":{"type":"string"},"options":{"type":"object","properties":{"1":{"type":"integer","description":"'key' is the option's id, 'value' is the option's value id"},"Stretcher frame":{"type":"string","description":"Here the 'key' is the option's name, 'value' is the option's value name"}}}}}}}},"SingleOrder":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the order."},"external_id":{"type":"string","description":"An optional external unique identifier for the order"},"is_test":{"type":"boolean","description":"A boolean indicating whether the order is a test order"},"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"status":{"type":"string","description":"The status of the order."},"status_label":{"type":"string","description":"A human-readable label for the order status."},"created_at":{"type":"string","description":"Creation date and timezone of the order."},"updated_at":{"type":"string","description":"The last update date and timezone of the order."},"shipments":{"type":"array","description":"An array of objects containing details about the shipment","items":{"properties":{"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"shipped_at":{"type":"string"},"items":{"type":"array","items":{"properties":{"item_id":{"type":"integer"},"item_external_id":{"type":"string"},"quantity":{"type":"integer"}}}}}}},"items":{"type":"array","description":"An array of objects representing the items in the order.","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier for the item."},"external_id":{"type":"string","description":"An optional external unique identifier for the item."},"variant_id":{"type":"string","description":"The unique identifier for the item variant."},"name":{"type":"string","description":"The name of the item."},"quantity":{"type":"integer","description":"The quantity of the item in the order."},"price":{"type":"number","description":"The price of the item."},"price_details":{"type":"object","description":"An object containing details about the price of the item.","properties":{"currency":{"type":"string","description":"The currency of the price."},"formatted":{"type":"string","description":"A human-readable representation of the price."},"in_subunit":{"type":"integer","description":"The price in the smallest unit of the currency"}}},"file":{"type":"string","description":"The URL of the image associated with the item"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"value":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}}}}},"totals":{"type":"object","properties":{"subtotal_amount":{"type":"number"},"subtotal_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"shipping_amount":{"type":"number"},"shipping_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"total_amount":{"type":"number"},"total_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"customs_shipping_costs":{"type":"number"},"customs_shipping_costs_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}}}}}},"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/orders":{"post":{"summary":"Create an order","description":"This API endpoint creates an order and returns it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPost"}}}},"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SingleOrder"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ### Get order ## Show an order > This API endpoint retrieves information about the specific order. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"SingleOrder":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the order."},"external_id":{"type":"string","description":"An optional external unique identifier for the order"},"is_test":{"type":"boolean","description":"A boolean indicating whether the order is a test order"},"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"status":{"type":"string","description":"The status of the order."},"status_label":{"type":"string","description":"A human-readable label for the order status."},"created_at":{"type":"string","description":"Creation date and timezone of the order."},"updated_at":{"type":"string","description":"The last update date and timezone of the order."},"shipments":{"type":"array","description":"An array of objects containing details about the shipment","items":{"properties":{"shipping_method":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},"tracking_number":{"type":"string"},"tracking_url":{"type":"string"},"shipped_at":{"type":"string"},"items":{"type":"array","items":{"properties":{"item_id":{"type":"integer"},"item_external_id":{"type":"string"},"quantity":{"type":"integer"}}}}}}},"items":{"type":"array","description":"An array of objects representing the items in the order.","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier for the item."},"external_id":{"type":"string","description":"An optional external unique identifier for the item."},"variant_id":{"type":"string","description":"The unique identifier for the item variant."},"name":{"type":"string","description":"The name of the item."},"quantity":{"type":"integer","description":"The quantity of the item in the order."},"price":{"type":"number","description":"The price of the item."},"price_details":{"type":"object","description":"An object containing details about the price of the item.","properties":{"currency":{"type":"string","description":"The currency of the price."},"formatted":{"type":"string","description":"A human-readable representation of the price."},"in_subunit":{"type":"integer","description":"The price in the smallest unit of the currency"}}},"file":{"type":"string","description":"The URL of the image associated with the item"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"value":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}}}}}}},"totals":{"type":"object","properties":{"subtotal_amount":{"type":"number"},"subtotal_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"shipping_amount":{"type":"number"},"shipping_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"total_amount":{"type":"number"},"total_amount_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}},"customs_shipping_costs":{"type":"number"},"customs_shipping_costs_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"integer"}}}}}}},"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/orders/{order_id}":{"get":{"summary":"Show an order","description":"This API endpoint retrieves information about the specific order.","parameters":[{"name":"order_id","in":"path","description":"`order_id` or `@external_id`","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SingleOrder"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ### Delete order ## Cancel an order > This API endpoint cancels a specific order. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}}},"paths":{"/orders/{order_id}":{"delete":{"summary":"Cancel an order","description":"This API endpoint cancels a specific order.","parameters":[{"name":"order_id","in":"path","description":"ID of the order","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Order successfully canceled"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ## **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:
StatusDescription
DraftOrder has been submitted but not yet confirmed.
AcceptedOrder has been confirmed and is being prepared for shipment.
FulfilledOrder has been completed and the product(s) is ready to be shipped.
GeneratedOrder has been generated
In ProgressOrder is in progress
CancelledOrder has been cancelled by the customer or admin.
RefundedOrder has been refunded to the customer.
Partial RefundOrder has been partially refunded to the customer.
PendingOrder has been placed by the customer and is waiting for payment to be completed.
ErrorSomething went wrong during the processing of the order.
## Parameters
KeyDescription
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.
shippingObject 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.firstnameEnd customer's first name.
shipping.lastnameEnd 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_primaryEnd customer's street name and house number.
shipping.street_secondary
(optional)		Additional address.
shipping.cityEnd customer's city name.
shipping.postcodeEnd customer's postal/zip code.
shipping.country_idEnd 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_codeIt 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.
itemsAn 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.quantityThe number of copies to produce of this particular item.
items.variant_codeThe 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_idcan 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_skuCan 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.fileThe 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.optionsA 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.
# Shipping ## Introduction Through the endpoints included in the Shipping section, you will be able to: * Calculate shipping rate for a given country and variant with specified quantity * Retrieve information about the shipping types * Retrieve information about the shipping methods * Retrieve a list of countries in our system * Retrieve a list of regions in a specific country ## Endpoints ### Shipping rates ## Calculate shipping rates > This API endpoint retrieves a list of calculated shipping rates for the given items and shipping info ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"ShippingPost":{"type":"object","properties":{"shipping":{"type":"object","required":["country"],"properties":{"country":{"type":"integer","description":"Please use /beta/countries to get country id value #/info/description"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/ShippingItem"}}}},"ShippingItem":{"type":"object","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer"},"variant_id":{"type":"integer","description":"Please use /beta/products/{product_id} to get a certain product variant id"}}},"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/shipping/rates":{"post":{"summary":"Calculate shipping rates","description":"This API endpoint retrieves a list of calculated shipping rates for the given items and shipping info","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingPost"}}}},"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"price_details":{"type":"object"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}} ``` ### Shipping types ## Show shipping types > This API endpoint retrieves a list of all available shipping types ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/shipping/types":{"get":{"summary":"Show shipping types","description":"This API endpoint retrieves a list of all available shipping types","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"code":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ### Shipping methods ## Show shipping methods > This API endpoint retrieves a list of all available shipping methods ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/shipping/methods":{"get":{"summary":"Show shipping methods","description":"This API endpoint retrieves a list of all available shipping methods","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An identifier for the shipping method."},"name":{"type":"string","description":"The name of the shipping method."}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ### Countries ## Show countries > This endpoint retrieves a list of countries with IDs and their corresponding codes. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/countries":{"get":{"summary":"Show countries","description":"This endpoint retrieves a list of countries with IDs and their corresponding codes.","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A string representing the name of the country."},"country_id":{"type":"integer","description":"An integer representing the unique ID of the country in our system."},"country_code":{"type":"string","description":"A string representing the ISO 3166-2 code of the country."}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ### Regions ## Show regions > This API endpoint retrieves the list of regions within a specific country by providing its ID. ```json {"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/regions/{country_id}":{"get":{"summary":"Show regions","description":"This API endpoint retrieves the list of regions within a specific country by providing its ID.","parameters":[{"name":"country_id","in":"path","description":"ID of country from our system","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the region in our system."},"code":{"type":"integer","description":"The region's code."},"name":{"type":"string","description":"The region's name."}}}}}}}}},"400":{"description":"Wrong argument"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}} ``` ## Parameters | Key | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `shipping` | An object that contains the country property. | | `shipping.country` | The ID of the country from our system, check `/api/beta/countries` for more information about the countries. | | `items` | An array of objects that contains information about the quantity and variant. | | `items.*.quantity` | Quantity of a variant. | | `items.*.variant_id` | The ID of the variant, please check `/api/beta/products/{product_id}` for more details about the variants. | # API V1 # Blueprints ## Introduction Through the endpoints included in the **Blueprints** section, you will be able to: * Retrieve all the available blueprints * Retrieve all the available blueprint variants * Retrieve all the available blueprint variant options *** ## Endpoints **Blueprint** is the foundation for any customizable product we offer — like a poster, mug, blanket, or canvas. Think of it as the **template** or **base model** of the product, before it has been customized by your customer. In simple terms, a **Blueprint** defines what kind of product your store can sell — and how it can be produced. For example: * **Blueprint**: Canvas * **Variants**: 20×20 cm, 30×30 cm, etc. * **Options**: Add-ons like different frames, hanger sets, or canvas borders While most products follow the general structure outlined above, some product types — especially apparel — may be structured differently. For example: * **Blueprint**: T-shirt * **Variants**: Different types (e.g., Premium Men's T Shirt, Women’s T Shirt) * **Options**: Sizes (e.g., S, M, L, XL) This flexible hierarchy allows us to support a wide range of product types. ## Show blueprints > This API endpoint retrieves a list of all available blueprints. ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/blueprints":{"get":{"tags":["Blueprints"],"summary":"Show blueprints","description":"This API endpoint retrieves a list of all available blueprints.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"type":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"variants_count":{"type":"integer"}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` *** The [blueprint's variants](#get-blueprints-blueprint-variants) endpoint provides detailed information about all variants of a specific blueprint. A **variant** typically represents a different version of the product — like a size, format, or type. When you call this endpoint, you’ll receive: * The ID of each variant * This is required when fetching related options via the [options](#get-blueprints-blueprint-variants-variant-options) endpoint * The name and type of the variant * Design area – the safe area for the print file on the variant (in mm) * Print file – full print area of the variant (in mm) * The price and formatted price * The production location (e.g., Europe or US) * Additional fields like tags, images, and design area specifications ## Show blueprint's variants > This API endpoint retrieves a list of all available blueprint's variants. ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/blueprints/{blueprint}/variants":{"get":{"tags":["Blueprints"],"summary":"Show blueprint's variants","description":"This API endpoint retrieves a list of all available blueprint's variants.","parameters":[{"name":"blueprint","in":"path","description":"The ID of the blueprint.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"production":{"type":"string"},"type":{"type":"string"},"trim":{"type":"integer"},"design_area":{"type":"object","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}},"printfile":{"type":"object","properties":{"width":{"type":"integer"},"height":{"type":"integer"}}},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string"}},"price":{"type":"number"},"price_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"number"}}}}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"}}}}}} ``` *** The [variant's options](#get-blueprints-blueprint-variants-variant-options) endpoint returns a list of **predefined SKU combinations** for a specific variant of a blueprint. Each item in the response represents **a complete configuration** — a unique combination of options that can be ordered. Once you’ve selected a base product (Blueprint) and a variant (like size or type), this endpoint gives you all the valid **option combinations** that define how the product can be manufactured. **What kind of data will you receive?** * A list of **SKU-level configurations** — each SKU represents a unique combination of a variant with specific options * The **SKU** identifier and descriptive name * The **price** of the SKU, including currency breakdown * The **option attributes**, such as: * Border types * Frame sizes * T-shirt colors * **Print area** and design file requirements (dimensions, DPI, and positioning) **How It Connects to Orders?** These SKUs act as **blank product templates** — they are used when placing an order **programmatically** via the [orders](/api-reference/api-v1/orders#post-orders) endpoint. When using this approach: * You provide the **SKU** (from this endpoint) in the product\_sku field of your order payload * Alongside the **SKU**, you include a **print file** (design or artwork) via a URL. This is ideal for **dynamically personalized** or **user-uploaded designs** that aren’t pre-configured in your product catalog. Alternatively, if you have already uploaded artwork to the Library, you can place orders using the associated image\_id. This allows you to reference existing assets without re-uploading them for every order. ## Show blueprint variant options > Retrieve options for a specific variant of a blueprint. ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/blueprints/{blueprint}/variants/{variant}/options":{"get":{"tags":["Blueprints"],"summary":"Show blueprint variant options","description":"Retrieve options for a specific variant of a blueprint.","parameters":[{"name":"blueprint","in":"path","description":"The ID of the blueprint.","required":true,"schema":{"type":"string"}},{"name":"variant","in":"path","description":"The ID of the variant.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"price_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"number"}}},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"option-key":{"type":"string"},"price":{"type":"number"},"price_details":{"type":"object","properties":{"currency":{"type":"string"},"formatted":{"type":"string"},"in_subunit":{"type":"number"}}}}}},"print_areas":{"type":"array","items":{"type":"object","properties":{"position":{"type":"string"},"width:":{"type":"integer"},"height":{"type":"integer"},"dpi":{"type":"integer"},"type":{"type":"string"},"required":{"type":"boolean"}}}}}}}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Blueprint variant or options not found."}}}}}} ``` # 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](/api-reference/api-v1/products#introduction) 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 > This API endpoint retrieves a list of all orders ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/orders":{"get":{"tags":["Orders"],"summary":"Get orders","description":"This API endpoint retrieves a list of all orders","parameters":[{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"order_id":{"type":"string"},"external_id":{"type":"string"},"country":{"type":"string"},"shipping_type":{"type":"string"},"is_test":{"type":"boolean"},"total_amount":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"fulfilled_at":{"type":"string"},"status":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` ## Show order > This API endpoint retrieves information about the order ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/orders/{order}":{"get":{"tags":["Orders"],"summary":"Show order","description":"This API endpoint retrieves information about the order","parameters":[{"name":"order","in":"path","description":"The ID of the order.","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":false,"schema":{"type":"string","default":"application/json"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"order_id":{"type":"string"},"external_id":{"type":"string"},"status":{"type":"string"},"shipping":{"type":"object","properties":{"email":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"company":{"type":"string"},"street_primary":{"type":"string"},"street_secondary":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"telephone":{"type":"string"}}},"shipping_type":{"type":"string"},"is_test":{"type":"boolean"},"total_amount":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"sub_total":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"shipping_total":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"customs_shipping":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"customs_costs":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"fulfilled_at":{"type":"string"},"packages":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"sku":{"type":"string"},"article":{"type":"object","properties":{"id":{"type":"integer"},"sku":{"type":"string"}}},"description":{"type":"string"},"quantity":{"type":"integer"},"unit_cost":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"taxes":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"total_item":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"metadata":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` ## POST /orders > Create order ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"Shipping":{"type":"object","properties":{"email":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"company":{"type":"string"},"street_primary":{"type":"string"},"street_secondary":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"},"country":{"type":"string"},"region":{"type":"string","description":"Required if the country is US or CA."},"telephone":{"type":"string"},"customs_shipping":{"type":"number"}},"required":["email","firstname","lastname","street_primary","city","postcode","country"]},"Billing":{"type":"object","description":"Override the default billing address. This is required for companies without a billing address.","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"company":{"type":"string"},"vat":{"type":"string"},"street_primary":{"type":"string"},"street_secondary":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"}},"required":["firstname","lastname","country","city","postcode","street_primary"]}}},"paths":{"/orders":{"post":{"tags":["Orders"],"summary":"Create order","description":"","parameters":[{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":true,"schema":{"type":"string","default":"application/json","enum":["application/json"]}}],"requestBody":{"required":true,"description":"Request body","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"external_id":{"type":"string"},"shipping_type":{"type":"string"},"is_test":{"type":"boolean"},"shipping":{"$ref":"#/components/schemas/Shipping"},"billing":{"$ref":"#/components/schemas/Billing"},"items":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"quantity":{"type":"integer"},"product_sku":{"type":"string"},"customs_value":{"type":"number"},"image_id":{"type":"string"}},"required":["quantity","product_sku","image_id"]}}},"required":["shipping_type","is_test","shipping","items"]},{"type":"object","properties":{"external_id":{"type":"string"},"shipping_type":{"type":"string"},"is_test":{"type":"boolean"},"shipping":{"$ref":"#/components/schemas/Shipping"},"billing":{"$ref":"#/components/schemas/Billing"},"items":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"quantity":{"type":"integer"},"product_sku":{"type":"string"},"customs_value":{"type":"number"},"file":{"type":"object","properties":{"front":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}},"required":["front"]}},"required":["quantity","product_sku","file"]}}},"required":["shipping_type","is_test","shipping","items"]},{"type":"object","properties":{"external_id":{"type":"string"},"shipping_type":{"type":"string"},"is_test":{"type":"boolean"},"shipping":{"$ref":"#/components/schemas/Shipping"},"billing":{"$ref":"#/components/schemas/Billing"},"items":{"type":"array","items":{"type":"object","properties":{"product_sku":{"type":"string"},"quantity":{"type":"integer"}},"required":["product_sku","quantity"]}}},"required":["shipping_type","is_test","shipping","items"]}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"Unprocessable Entity"}}}}}} ``` ## PUT /orders/{order}/accept > Accept order ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/orders/{order}/accept":{"put":{"tags":["Orders"],"summary":"Accept order","description":"","parameters":[{"name":"order","in":"path","description":"The ID of the order.","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":true,"schema":{"type":"string","default":"application/json","enum":["application/json"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` ## PUT /orders/{order}/update-address > Update order's address ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/orders/{order}/update-address":{"put":{"tags":["Orders"],"summary":"Update order's address","description":"","parameters":[{"name":"order","in":"path","description":"The ID of the order.","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":true,"schema":{"type":"string","default":"application/json","enum":["application/json"]}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"telephone":{"type":"string"},"firstname":{"type":"string"},"lastname":{"type":"string"},"company":{"type":"string"},"street_primary":{"type":"string"},"street_secondary":{"type":"string"}},"required":["firstname","lastname","street_primary"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}} ``` *** ## Parameters
FieldTypeRequiredDescription
external_idstringfalseUnique identifier for your orders
shipping_typestringtrueShipping type — currently, only tracked shipping is supported.
is_testbooleantrueWhen value is set to true, then the order will be created as a test order, it will not be produced nor shipped
shippingobjecttrueContains the address and required information about end customer
shipping.emailstringtrueCustomer's email address
shipping.firstnamestringtrueCustomer's first name
shipping.lastnamestringtrueCustomer's last name
shipping.companystringfalseCustomer's company name, used when the end customer is ordering on behalf of a company
shipping.street_primarystringtrueCustomer's street address
shipping.street_secondarystringfalseCustomer's additional address
shipping.citystringtrueCustomer's city
shipping.postcodestringtrueCustomer's postcode
shipping.countrystringtrueCustomer's country, ISO 3166-1 alpha-2 standard
shipping.regionstringfalse

Customer's region.

❗ Required for US and CA.

shipping.telephonestringfalseCustomer's phone number
shipping.customs_shippingnumberfalseThis value is used to print the shipping costs shown on the Customs Declaration
billingobjectfalse

Override the default billing address

❗ This is required for companies without a billing address

billing.firstnamestringtrueCustomer's first name
billing.lastnamestringtrueCustomer's last name
billing.companystringfalseCustomer's company
billing.vatstringfalseCustomer's VAT
billing.street_primarystringtrueCustomer's street address
billing.street_secondarystringfalseCustomer's additional address
billing.countrystringtrueCustomer's country
billing.regionstringfalseCustomer's region
❗Required for US and CA.
billing.citystringtrueCustomer's city
billing.postcodestringtrueCustomer's postcode
itemsarraytrueAn array with on or more items
items.external_idstringfalseUnique identifier for your items
items.quantityintegertrueThe number of copies to produce of this particular item
items.customs_valuenumberfalseThis value is used to print the shipping costs shown on the Customs Declaration
items.product_skustringtrueThe product SKU which may or may not include the associated artwork.
items.image_idstringtrue

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.fileobjecttrue❗Required when items.product_sku does not include artwork or items.image_id is not provided
items.file.front.urlstringtrueURL of the print file
# Library ## Introduction Through the endpoints included in the **Library** section, you will be able to: * Retrieve all the available images from the library * Retrieve an image from the library * Add an image to the library ## Endpoints ## Show library > This API endpoint retrieves a list of all images from your library ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/library":{"get":{"tags":["Library"],"summary":"Show library","description":"This API endpoint retrieves a list of all images from your library","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"image_id":{"type":"string"},"file_name":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"string"},"image_url":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` ## Show an image from the library > This API endpoint retrieves an images from your library ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/library/{image}":{"get":{"tags":["Library"],"summary":"Show an image from the library","description":"This API endpoint retrieves an images from your library","parameters":[{"name":"image","description":"The ID of the image.","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"image_id":{"type":"string"},"file_name":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"string"},"image_url":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Not found."}}}}}} ``` ## Post a new image to the library > This API endpoint allows you to upload a new image to your library ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/library":{"post":{"tags":["Library"],"summary":"Post a new image to the library","description":"This API endpoint allows you to upload a new image to your library","parameters":[{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":true,"schema":{"type":"string","default":"application/json","enum":["application/json"]}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string"},"url":{"type":"string"}},"required":["file_name","url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"image_id":{"type":"string"},"file_name":{"type":"string"},"upload_date":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` # Products ## Introduction Through the endpoints included in the **Products** section, you will be able to: * Retrieve a list of all the products * Retrieve details about a specific product *** **Product** refers to a fully configured, ready-to-sell item that has been created through the **product configurator in merchOne dashboard**. Unlike **Blueprints**, which are general templates requiring custom artwork and manual selection of options, **Products** are **complete listings** — they already have: * A selected blueprint (e.g., Canvas, T-shirt) * Chosen options (e.g., White border, 2 cm frame) * An attached artwork * One or more preview images * A unique, artwork-specific SKU These products are essentially what a customer would see in the storefront — finished, designed, and ready to order or publish. **Why This Matters?** These pre-configured products are ideal for: * Brands with fixed collections (e.g., an art print series) * Shops that want fast deployment with no need for dynamic customization * Avoiding extra integration work for sending print files with each order If your use case involves end-user customization or upload (e.g., photo gifts), you'll likely use the **Blueprint** approach. But if you're selling pre-designed SKUs, these Products are a faster, cleaner path. ## Endpoints The [products](#get-products) endpoint returns a list of all configured products, including: * Product name and description * Tags (like “canvas”, “mug”) * Preview images * The full **product\_sku** (including the artwork reference) * Published status (helpful for managing visibility) ## Show products > This API endpoint retrieves a list of all products ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/products":{"get":{"tags":["Products"],"summary":"Show products","description":"This API endpoint retrieves a list of all products","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"product_sku":{"type":"array","items":{"type":"string"}},"published":{"type":"boolean"},"previews":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` *** The [product's details](#get-products-product) endpoint returns detailed information about a specific product, such as: * SKU (e.g., CVS0200201LWF2-APO12345678) * The first part represents the blueprint + variant + options * The APO12345678 suffix links to the embedded artwork * Selected options (e.g., border, frame) * Markup and pricing info * Preview images for display or marketing * Whether the product is published or still in draft ## Show product > This API endpoint retrieves information about the product ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/products/{product}":{"get":{"tags":["Products"],"summary":"Show product","description":"This API endpoint retrieves information about the product","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"options":{"type":"object","properties":{"option-key":{"type":"string"}}},"markup":{"type":"string"},"cost":{"type":"string"},"price":{"type":"string"},"published":{"type":"boolean"},"previews":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` # Shipping rates ## Introduction Through the endpoint included in the **Shipping rates** section, you will be able to: * Get information about shipping rates ## Endpoints ## Calculate shipping rates > This endpoint calculate shipping rates by given address and products ```json {"openapi":"3.0.3","info":{"title":"MerchOne API","version":"1.0.0"},"servers":[{"url":"https://api.merchone.com/api/v1"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}}},"paths":{"/shipment/rates":{"post":{"tags":["Shipment rates"],"summary":"Calculate shipping rates","description":"This endpoint calculate shipping rates by given address and products","parameters":[{"name":"Accept","in":"header","description":"Media type(s) that is/are acceptable for the response","required":true,"schema":{"type":"string","default":"application/json","enum":["application/json"]}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"zipcode":{"type":"string"},"country":{"type":"string"}},"required":["zipcode","country"]},"order":{"type":"array","items":{"type":"object","properties":{"product_sku":{"type":"string"},"quantity":{"type":"integer"}},"required":["product_sku","quantity"]}}},"required":["address","order"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"cost":{"type":"number"},"currency":{"type":"string"}}}}}}}}},"401":{"description":"Unauthorized"}}}}}} ``` # Webhooks > **Note:** This page provides technical guidance on configuring and receiving webhook notifications from merchOne. For instructions on setting up your merchOne account, managing stores, and using the merchOne application, please visit the [merchOne Knowledge Base](https://service.merchone.com/knowledge). To explore merchOne’s available products and services, please visit [merchOne.com](https://merchone.com/). ## Introduction Webhooks allow your application to receive real-time notifications about events in your merchOne orders. When specific events occur (order cancellation, shipment, tracking updates, etc.), merchOne sends a `POST` request to your configured webhook URL with event details in JSON format. ## Configuration {% stepper %} {% step %} ### Log in and open dashboard Log in to your merchOne account and navigate to the dashboard. {% endstep %} {% step %} ### Open Stores settings Navigate to the **Stores** page and access the **Settings** for the specific store where you wish to add a webhook. {% endstep %} {% step %} ### Find the Webhook section Scroll to the **Webhook** section. {% endstep %} {% step %} ### Add your webhook URL Add your webhook URL to the **Webhook URL** field. {% endstep %} {% step %} ### Save Click **Save**. {% endstep %} {% endstepper %} {% hint style="warning" %} The webhook URL is stored with the order at creation time. If you change or remove the webhook URL after an order is created, the changes will **not** apply to existing orders. Make sure your webhook URL is correctly configured before placing orders. {% endhint %} ## Webhook Delivery ### Request Format * Method: `POST` * Content-Type: `application/json` * Timeout: 60 seconds ### Retry Policy If your webhook endpoint fails to respond with a `2xx` status code, merchOne will automatically retry the delivery: | Attempt | Wait Time | | --------- | ---------- | | 1st retry | 1 minute | | 2nd retry | 5 minutes | | 3rd retry | 10 minutes | | 4th retry | 20 minutes | | 5th retry | 30 minutes | If your endpoint accumulates 10 or more failed webhook deliveries in a single day, you will receive a notification email. ### Expected Response Your endpoint should return a `200 OK` (or any `2xx`) status code to acknowledge receipt. The response body is ignored. ``` HTTP/1.1 200 OK ``` ## Webhook Events merchOne supports the following webhook event types: | Event Type | Description | | ------------------------- | --------------------------------------------------- | | `shipment_sent` | Triggered when an order shipment is dispatched | | `shipment_tracking_event` | Triggered when a tracking status update is received | | `order_canceled` | Triggered when an order is canceled | | `order_failed` | Triggered when an order encounters an error | | `order_commented` | Triggered when a comment is added to an order | ### Event-Specific Data Fields Each webhook event includes the full `order` object plus event-specific data: | Event Type | Extra Fields | Description | | ------------------------- | ------------ | -------------------------------------------------- | | `shipment_sent` | `shipment` | Shipment details with tracking info and items | | `shipment_tracking_event` | `event` | Tracking status, location, details, and date | | `order_canceled` | `author` | Who canceled the order (API, System, or user name) | | `order_failed` | `reason` | Error message describing why the order failed | | `order_commented` | `comment` | The comment text added to the order | ## Event Payloads ### Shipment Sent (`shipment_sent`) Triggered when an order shipment is dispatched from the fulfillment center. {% code title="shipment\_sent.json" %} ```json { "type": "shipment_sent", "created": "2025-05-02T12:48:56.000000Z", "data": { "shipment": { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] }, "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FULFILLED", "status_label": "Fulfilled", "created_at": "2025-05-02T12:45:35.000000Z", "updated_at": "2025-05-02T12:48:56.000000Z", "shipments": [ { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] } ], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ### Shipment Tracking Event (`shipment_tracking_event`) Triggered when a tracking status update is received for a shipment. {% code title="shipment\_tracking\_event.json" %} ```json { "type": "shipment_tracking_event", "created": "2025-05-03T08:15:00.000000Z", "data": { "event": { "status": "in_transit", "location": "Berlin, Germany", "details": "Package is in transit to destination", "date": "2025-05-03T08:12:00.000000Z" }, "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FULFILLED", "status_label": "Fulfilled", "created_at": "2025-05-02T12:45:35.000000Z", "updated_at": "2025-05-03T08:15:00.000000Z", "shipments": [ { "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "tracking_number": "00340434161094042557", "tracking_url": "https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=00340434161094042557", "shipped_at": "2025-05-02T12:48:56.000000Z", "items": [ { "item_id": 12345, "item_external_id": "your-sku-123", "quantity": 3 } ] } ], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} Possible tracking statuses: * `in_transit` - Package is on the way * `out_for_delivery` - Package is out for delivery * `delivered` - Package has been delivered * `exception` - Delivery exception occurred * `returned` - Package returned to sender ### Order Canceled (`order_canceled`) Triggered when an order is canceled. {% code title="order\_canceled.json" %} ```json { "type": "order_canceled", "created": "2025-11-27T10:26:09.000000Z", "data": { "author": "via API", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "CANCELED", "status_label": "Canceled", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:09.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} Possible `author` values: * `"via API"` - Canceled via API request * `"by System (Automatic)"` - Automatically canceled by the system * `"by John Doe"` - Canceled by a user * `"by our administrator, John Doe"` - Canceled by an admin ### Order Failed (`order_failed`) Triggered when an order encounters an error during processing. {% code title="order\_failed.json" %} ```json { "type": "order_failed", "created": "2025-11-27T10:26:19.000000Z", "data": { "reason": "Invalid image file: minimum resolution requirement not met", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "FAILED", "status_label": "Failed", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:19.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ### Order Commented (`order_commented`) Triggered when a comment is added to an order by merchOne staff. {% code title="order\_commented.json" %} ```json { "type": "order_commented", "created": "2025-11-27T10:26:28.000000Z", "data": { "comment": "Your order is being prepared with special care.", "order": { "id": "PPO12345678", "external_id": null, "is_test": false, "shipping_method": { "code": "DHL_STANDARD", "name": "DHL Standard" }, "status": "IN_PRODUCTION", "status_label": "In Production", "created_at": "2025-11-27T09:00:00.000000Z", "updated_at": "2025-11-27T10:26:28.000000Z", "shipments": [], "items": [ { "id": 12345, "external_id": "your-sku-123", "variant_id": 1, "name": "20x20 cm", "quantity": 3, "price": 5.33, "price_details": { "currency": "EUR", "formatted": "5.33 €", "in_subunit": 533 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 }, "file": "https://api.merchone.com/files/orders/PPO12345678/image.png", "options": [ { "id": 1, "name": "Canvas border", "value": { "id": 2, "name": "Folded" } }, { "id": 2, "name": "Stretcher frame", "value": { "id": 6, "name": "2 cm" } } ], "retail_price": null, "retail_price_details": null } ], "totals": { "subtotal_amount": 15.99, "subtotal_amount_details": { "currency": "EUR", "formatted": "15.99 €", "in_subunit": 1599 }, "shipping_amount": 3.02, "shipping_amount_details": { "currency": "EUR", "formatted": "3.02 €", "in_subunit": 302 }, "total_amount": 19.01, "total_amount_details": { "currency": "EUR", "formatted": "19.01 €", "in_subunit": 1901 }, "customs_shipping_costs": 5.99, "customs_shipping_costs_details": { "currency": "EUR", "formatted": "5.99 €", "in_subunit": 599 }, "grand_total": 22.62, "grand_total_details": { "currency": "EUR", "formatted": "22.62 €", "in_subunit": 2262 }, "tax_amount": 3.61, "tax_amount_details": { "currency": "EUR", "formatted": "3.61 €", "in_subunit": 361 } }, "retail_costs": [] } } } ``` {% endcode %} ## Troubleshooting ### Not receiving webhooks? {% stepper %} {% step %} ### Verify webhook URL Verify your webhook URL is correctly configured in Store Settings. {% endstep %} {% step %} ### Check endpoint accessibility Ensure your endpoint is publicly accessible (not behind a firewall). {% endstep %} {% step %} ### Return correct status Check that your endpoint returns a `200 OK` response. {% endstep %} {% step %} ### Verify SSL Verify your SSL certificate is valid (HTTPS required). {% endstep %} {% endstepper %} # Print files > **Note:** This section provides technical requirements for submitting print files through the API. For detailed guidance on preparing print-ready artwork, including file formats, color profiles, resolution, dimensions, bleed, and other important considerations, please see [How to Create the Perfect Print File](https://service.merchone.com/knowledge/how-to-create-the-perfect-print-file). **Providing print files** To provide a print file to the API, provide a file path on a web server in the JSON node "file" within the "items" dictionary. We recommend using an obfuscated path which also contains an authentication token or session ID to make sure the files cannot be accessed freely on the internet. Also, make sure to set the path where the files are stored on the server to "noindex, nofollow" in your "robots.txt", to make sure search engines do not try to index it. Example: [https://www.example.com/download\_print\_data/12345/6789?token=XJRHAZQU76AU41KJNIHV1MQJ](https://api.picanova.com/docs#) The print file is downloaded as soon as the order is read into our system, but since processing/downloading can take some time, we recommend to either calculate print files on demand by a server-side controller or, when you prepare them in advance, store them on the server for a certain period to allow our systems to download and process them before you delete them from your server. **File format** Print files can be provided in JPEG or PNG format. JPEG files are preferred for better compression, except when transparency is required (e.g. for the T-Shirt product). We suggest using the **eciRGB v2 color profile** when preparing your designs. Starting with the correct color model and profile for your intended output helps avoid conversion issues and ensures the best possible quality for your print-on-demand products. Other color profiles and color spaces can be processed, but color shifts or a loss of print quality may occur during conversion. For a complete guide to RGB, CMYK, and color profiles, please see [What is the difference between RGB and CMYK color models?](https://service.merchone.com/knowledge/what-is-the-difference-between-rgb-and-cmyk-color-models). **Resolution and aspect ratio** Print files must be provided with sufficient resolution and the correct aspect ratio. Some sanity checks are done by our systems to protect against the most common usage errors, but generally, the customer is responsible to provide correct print files for the orders. Please note that the resolution/dpi value saved in the files is ignored by the system since the files are automatically scaled to fit the product. Instead the size, i.e. the width and height in pixels, needs to be sufficient to fulfill the minimum resolution for the product. Please use the "products" API to retrieve the information about the minimum resolution for each product, as well as the aspect ratio your files should have. **Example**: The Puzzle product has a minimum resolution of 72 dpi (dots per inch), and the variant "20x27 cm - 88 Pieces" has a print file size of 270x200 millimeters. The minimum size of the image in pixels is therefore 765x567 (270 / 25.4 \* 72, 200 / 25.4 \* 72), but you can improve print quality by providing a larger file. Still, you must make sure that the aspect ratio (the ratio between width and height) always matches a ratio of 27:20.\ \ A notable exception to this rule is the "Canvas" product when used in conjunction with the FOLDED border effect. The FOLDED border effect allows the customer to specify the portion of the image wrapped around the stretcher frame of the Canvas. This means that in this case, the print file must include an image border to wrap around the stretcher frame. The border must be 25mm for the 2cm stretcher frame and 45mm for the 4cm stretcher frame. For example, for a 40x30cm canvas, when using a FOLDED border effect with a 2cm stretcher frame, the effective size of the print file must be 45x35cm. This changes the required aspect ratio from 4:3 to 9:7 (45:35) and also increases the minimum pixel size. However, this is only required when using the FOLDED border effect, not when using one of the other border effects like STRETCHED or MIRRORED since the latter creates the border automatically. The print file provided for the "Rug" product must include an image border of 30mm, which will later be trimmed in the production process. For example, for a 70x50 cm rug, the effective size of the print file must be 76x56 cm. This changes the required aspect ratio from 7:5 to 19:14 (76:56) and increases the minimum pixel size to 18 dpi (dots per inch). Depending on the product, files above a certain resolution only increase storage space and system load but do not improve print quality. For almost all products, files with a resolution larger than 300dpi do not make sense in practice.