> For the complete documentation index, see [llms.txt](https://docs.merchone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.merchone.com/api-reference/api-v1/orders.md). # 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.md#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