Skip to main content

Create an order using the Mintsoft API

Learn how to create an order using the Mintsoft application programming interface (API), including required fields, optional parameters and an example request.

Written by Tom Higgs

This article is for customers with custom-built third-party application programming interface (API) integrations. It describes an additional method for creating orders, rather than the standard approach.

To create an order using a custom API integration, use the PUT /api/Order request. The order contains details of who it is being shipped to and the products you want to ship.

Important: If you are a third-party logistics (3PL) user, Mintsoft carries out a unique check on the ExternalOrderReference, Source Order ID and Order Number against each individual 3PL client.

Required fields

ClientId (Admin users only)

When you create an order as an Admin user, you must specify the ClientId to show which client the order belongs to. Client users do not need to specify this field, as it defaults to their own ClientId.

For example:

ClientId: 123

Warehouse

Specify the warehouse you want to create the order against. You can do this by name or ID.

For example:

WarehouseID: 3 Warehouse: Main Warehouse

To find a full list of available warehouses, use the GET /api/Warehouse request.

Country

Specify the country you are shipping the order to. You can do this by name or ID. You can use ISO 2-digit codes, ISO 3-digit codes or country names.

For example:

CountryID: 1 Country: UK

To find a full list of countries, use the GET /api/RefData/Countries request.

CourierService (or AUTO)

Specify how the order is sent. You can do this using a generic term that you can map to rules, or a specific courier ID or name.

For example:

CourierServiceID: 12 CourierService: NEXT DAY CourierService: DPD NEXT DAY

To let Mintsoft automatically select the appropriate courier based on your rules, set CourierService to AUTO.

To find a full list of courier services, use the GET /api/Courier/Services request.

Order items

Specify a list of the items on the order. For each product, you can use either the stock keeping unit (SKU) or the exact ProductId.

Important: If you do not provide a unit price for the products on the order, Mintsoft does not pull the product price from the product record. The unit price is set to zero.

Optional fields

Channel

Specify the channel the order came from, for example, website, wholesale or retail. You can do this by name or ID.

For example:

ChannelID: 1 Channel: Retail Website

Additional order item fields

You can include the following optional fields for each order item:

  • Details: Additional item description.

  • Discount: Discount amount for this item.

  • WarehouseId: Override warehouse for this item, for multi-warehouse orders.

  • RequestedSerialNo: Request a specific serial number.

  • RequestedBatchNo: Request a specific batch number.

  • RequestedBBEDate: Request a specific best before date.

Order date fields

To schedule delivery and despatch, you can include the following fields:

  • RequiredDeliveryDate: Target delivery date.

  • RequiredDespatchDate: Target despatch date.

Note: DeliveryDate and DespatchDate are deprecated. Use RequiredDeliveryDate and RequiredDespatchDate instead.

Financial details

To provide a detailed financial breakdown, you can include the following fields:

  • ShippingTotalExVat: Shipping cost excluding VAT.

  • ShippingTotalVat: VAT amount on shipping.

  • DiscountTotalExVat: Discount amount excluding VAT.

  • DiscountTotalVat: VAT amount on the discount.

  • TotalVat: Total VAT for the entire order.

Tax and customs information

For international orders and customs documentation, you can include the following fields:

  • VATNumber: VAT registration number.

  • EORINumber: Economic Operators Registration and Identification (EORI) number.

  • PIDNumber: Personal Identification Number.

  • UKIMSNumber: UK Internal Market Scheme number.

  • RFCNumber: Tax registration number (Mexico).

  • IOSSNumber: Import One-Stop Shop number (EU).

Tags

You can add tags to orders when you create them, as a comma-separated string. You can use tags for filtering and automation rules.

Custom name-value pairs

You can add custom metadata to orders and order items using name-value pairs. This is useful for personalisations, gift messages or custom fields.

Additional optional fields

  • NumberOfParcels: Number of parcels for this order. This affects shipping label generation.

  • NationalAddressField: Country-specific address identifier, for example, CPF for Brazil or RFC for Mexico.

Example request with optional fields

The following example shows an API order that includes optional fields:

{   "OrderItems": [{     "SKU": "TEST-PRODUCT-1",     "Quantity": 1,     "UnitPrice": 10,     "UnitPriceVat": 2   }],   "OrderNumber": "MY ORDER NUMBER",   "ExternalOrderReference": "EXT-12345",   "ClientId": 123,   "Title": "MR",   "CompanyName": "MY COMPANY NAME",   "FirstName": "FIRST NAME",   "LastName": "LAST NAME",   "Address1": "First Line Address",   "Address2": "Second Line Address",   "Address3": "Third Line Address",   "Town": "Town or City",   "County": "County or State",   "PostCode": "PostCode or ZipCode",   "Country": "GB",   "Email": "[email protected]",   "Phone": "01245123456",   "Mobile": "07979000000",   "CourierService": "Next Day",   "Warehouse": "Main Warehouse",   "Currency": "GBP",   "Comments": "Please pack in a safe box",   "DeliveryNotes": "Delivery Message",   "GiftMessages": "Gift Message",   "OrderValue": 12,   "NumberOfParcels": 1,   "RequiredDeliveryDate": "2024-12-25T00:00:00",   "Tags": "Priority,Gift",   "VATNumber": "GB123456789",   "OrderNameValues": [     {"Name": "GiftWrap", "Value": "Yes"}   ] }

Complete field reference

The following lists show all available fields for the API create order endpoint.

Required fields

Order level:

  • Warehouse (or WarehouseId)

  • Country (or CountryId)

  • OrderItems (array, which must contain at least one item)

Order item level (for each item):

  • SKU (or ProductId)

  • Quantity

Admin users only:

  • ClientId

Optional fields

Order level, basic information:

  • OrderNumber

  • ExternalOrderReference

  • Title

  • CompanyName

  • FirstName

  • LastName

  • Address1

  • Address2

  • Address3

  • Town

  • County

  • PostCode

  • Email

  • Phone

  • Mobile

Order level, shipping and delivery:

  • CourierService (or CourierServiceId)

  • NumberOfParcels

  • RequiredDeliveryDate

  • RequiredDespatchDate

  • DeliveryNotes

Order level, financial:

  • Currency (or CurrencyId)

  • OrderValue

  • ShippingTotalExVat

  • ShippingTotalVat

  • DiscountTotalExVat

  • DiscountTotalVat

  • TotalVat

Order level, tax and customs:

  • VATNumber

  • EORINumber

  • PIDNumber

  • UKIMSNumber

  • RFCNumber

  • IOSSNumber

Order level, additional:

  • Comments

  • GiftMessages

  • Channel (or ChannelId)

  • Tags

  • RecipientType

  • NationalAddressField

  • OrderNameValues (array)

  • ConnectAction (object)

  • CashOnDelivery (object with Amount and CurrencyCode)

Order item level:

  • UnitPrice

  • UnitPriceVat

  • Discount

  • Details

  • WarehouseId

  • RequestedSerialNo

  • RequestedBatchNo

  • RequestedBBEDate

  • OrderItemNameValues (array)

Deprecated fields

Important: Do not use the following fields. They are no longer supported.

  • DeliveryDate

  • DespatchDate

Related Articles
Did this answer your question?