API - Create an order | Mintsoft Help Centre

This guide is intended for customers with custom-built third-party API integrations. It provides an additional method for creating orders, rather than the standard approach. To create a new order via a custom API, you need to use the PUT /api/Order request. The order contains details about who it's being shipped to as well as the products that you want to ship.

Important: (3PL Only) Please be advised, we do a unique check on the ExternalOrderReference and Order Number against each individual 3PL client.

ClientId - required for Admin users

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

Example:

ClientId: 123

Warehouse - required

When creating an order you need to 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

You can find a full list of available warehouses using the GET /api/Warehouse request.

Country - required

You need to specify the country you're shipping the order to. You can do this by Name or ID, for example:

CountryID: 1
Country: UK

The country can be ISO 2 or 3 digit codes or country names.

You can find a full list of countries using the GET /api/RefData/Countries request.

CourierService - required (or AUTO)

You need to specify how the order is sent. You can do this using a generic term, which you can map to rules or a specific courier ID or name, for example:

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

You can set CourierService to 'AUTO' to let the system automatically select the appropriate courier based on your rules.

You can find a full list of courier services using the GET /api/Courier/Services request.

Channel - optional

When creating an order you can specify a channel that the order came from, for example, website, wholesale, retail. You can do this by name or ID, for example:

ChannelID: 1
Channel: Retail Website

Order items - required

You need to specify a list of items that are on the order. When specifying the product, you can either use the SKU or the exact ProductId. Please note, if you don't provide unit price for the products on the order, it won't pull the product price from Mintsoft; the unit price will be set to zero.

Additional order item fields

You can include additional optional fields for each order item:

Details: Additional item description.
Discount: Discount amount for this item.
WarehouseId: Override warehouse for this specific item (for multi-warehouse orders).
RequestedSerialNo: Request specific serial number
RequestedBatchNo: Request specific batch number
RequestedBBEDate: Request specific best before date

Order date fields - optional

For delivery and despatch scheduling, you can include:

RequiredDeliveryDate: Target delivery date
RequiredDespatchDate: Target despatch date

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

Financial details - optional

You can provide detailed financial breakdowns:

ShippingTotalExVat: Shipping cost excluding VAT
ShippingTotalVat: VAT amount on shipping
DiscountTotalExVat: Discount amount excluding VAT
DiscountTotalVat: VAT amount on discount
TotalVat: Total VAT for the entire order

Tax and customs information - optional

For international orders and customs documentation, you can include:

VATNumber: VAT registration number
EORINumber: Economic Operators Registration and Identification number
PIDNumber: Personal Identification Number
UKIMSNumber: UK Internal Market Scheme number
RFCNumber: Tax registration number (Mexico)
IOSSNumber: Import One-Stop Shop number (EU)

Tags - optional

You can add tags to orders during creation as a comma-separated string. Tags can be used for filtering and automation rules.

Custom name-value pairs - optional

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 (affects shipping label generation).
NationalAddressField: Country-specific address identifier (e.g., CPF for Brazil, RFC for Mexico).

API order example with 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"}
  ]
}