Skip to main content

Creating Sales Orders

Sales orders are used for managing orders and creating shipments through the Shipmondo App. They support features such as packing slips, payment capture, address validation, and much more.

Select your addresses​

To assign a shipping address that will be used when a shipment is created, use the ship_to object. It is also possible to set a billing address, by using the bill_to object. If the bill_to object is not set, it will be set to be the same as ship_to.

info

The country_code must always be provided in the ISO 3166-1 alpha-2 format.

"ship_to": {
    "name": "Lene Jensen",
    "attention": null,
    "address1": "Vindegade 112",
    "address2": null,
    "zipcode": "5000",
    "city": "Odense C",
    "country_code": "DK",
    "email": "lene@email.dk",
    "mobile": "50607080",
    "telephone": "50607080",
    "instruction": null
  },
"bill_to": {
    "name": "Min Virksomhed ApS",
    "attention": null,
    "address1": "Strandvejen 6",
    "address2": null,
    "zipcode": "5240",
    "city": "Odense NØ",
    "country_code": "DK",
    "email": "firma@email.dk",
    "mobile": "70400407",
    "telephone": "70400407"
  }

Service point​

Similar to imported shipments and shipments, a service point can be specified if the shipment is to be delivered to a specific service point. A service point can be retrieved from the /pickup_points end point. Read more about it here

A service point is specified as follows:

"service_point": {
    "id": "95558",
    "name": "Påskeløkkens Købmand",
    "address1": "Paaskeløkkevej 11",
    "address2": null,
    "zipcode": "5000",
    "city": "Odense C",
    "country_code": "DK"
  }

Payment details​

Payment details specify the general payment information about an order, such as overall amount, the specified tax (VAT %), and currency. They also contain information that is needed for payment capture:

  • transaction_id uniquely identifies the transaction as specified in the selected payment gateway.
  • authorized_amount is the amount authorised for the transaction.
  • payment_method is the method in which the order was paid, and should be uniquely bound to a payment_gateway through the payment_gateway_id. If a payment_method with the same name already exists, the relation between the gateway and the method will be updated.
  • payment_gateway_id identifies the payment gateway created through the Shipmondo App. To find the id of the payment gateway, use the /payment_gateways endpoint.
info

The currency_code must always be provided in the ISO 4217 code format.

 "payment_details": {
    "amount_excluding_vat": "1600.0",
    "amount_including_vat": "2000.0",
    "authorized_amount": "2000.0",
    "currency_code": "DKK",
    "vat_amount": "400.0",
    "vat_percent": "0.25",
    "payment_method": "quickpay",
    "transaction_id": "123456789",
    "payment_gateway_id": "4012"
  }

Creating order lines​

Order lines is an array of lines used to specify different product lines that are a part of an order. The type of the line is specified by line_type and can be one of the following:

  • item
  • shipping
  • discount
  • giftcard

The line contains fields used to identify the line, such as item_name, item_sku, and item_variant_code.

When providing price details for the specified line, the following fields will be used to calculate the totals of the line.

  • quantity is the amount of units for this item line.
  • unit_price_excluding_vat is the price for one of the items without tax.
  • vat_percent is the tax percentage in decimals, which means 25% is 0.25.

An item will be created for each unique item_sku in all sales orders requests. The items can be found under Products in the Shipmondo App.

info

When the line_type is either discount or giftcard, the unit_price_excluding_vat should be negative, as it subtracts from the total amount.

"order_lines": [
   {
     "line_type": "item",
     "item_name": "T-Shirt",
     "item_sku": "TS001-WH",
     "item_variant_code": "White",
     "quantity": "2.0",
     "unit_price_excluding_vat": "800.0",
     "discount_amount_excluding_vat": "0.0",
     "vat_percent": "0.25",
     "currency_code": "DKK"
   }
 ]

Assigning a shipment template​

Shipment templates are used to pre-fill shipping information, such as carrier, delivery product, weight etc. for achieving a higher level of automation.

To find the shipment templates associated with a specific Shipmondo account, use the /shipment_templates endpoint. From the response, a shipment template id can be found and then applied to the root of the sales order request as follows:

"shipment_template_id": "177"

Creating the sales order request​

With each of the elements provided as described in the previous sections, a sales order request is almost fully formed.

Adding order_id, source_name, ordered_at, and archived determines how those orders are viewed in the Shipmondo App.

Here is an example of a full request:

{
  "order_id": "27016",
  "ordered_at": "2018-10-17T15:25:44.557+02:00",
  "source_name": "Testcompany ApS",
  "archived": false,
  "shipment_template_id": "177",
  "ship_to": {
    "name": "Lene Jensen",
    "attention": null,
    "address1": "Vindegade 112",
    "address2": null,
    "zipcode": "5000",
    "city": "Odense C",
    "country_code": "DK",
    "email": "lene@email.dk",
    "mobile": "50607080",
    "telephone": "50607080",
    "instruction": null
  },
  "bill_to": {
    "name": "Pakkelabels.dk ApS",
    "attention": null,
    "address1": "Strandvejen 6",
    "address2": null,
    "zipcode": "5240",
    "city": "Odense NØ",
    "country_code": "DK",
    "email": "firma@email.dk",
    "mobile": "70400407",
    "telephone": "70400407"
  },
  "service_point": {
    "id": "95892"
  },
  "payment_details": {
    "amount_excluding_vat": "1600.0",
    "amount_including_vat": "2000.0",
    "authorized_amount": "2000.0",
    "currency_code": "DKK",
    "vat_amount": "400.0",
    "vat_percent": "0.25",
    "payment_method": "quickpay",
    "transaction_id": "123456789",
    "payment_gateway_id": "4012"
  },
  "order_lines": [
    {
      "line_type": "discount",
      "item_name": "Shipping discount",
      "item_sku": null,
      "item_variant_code": null,
      "quantity": "1.0",
      "unit_price_excluding_vat": "-80.0",
      "discount_amount_excluding_vat": "0.0",
      "vat_percent": "0.25",
      "currency_code": "DKK"
    },
    {
      "line_type": "item",
      "item_name": "T-Shirt",
      "item_sku": "TS001-WH",
      "item_variant_code": "White",
      "quantity": "2.0",
      "unit_price_excluding_vat": "800.0",
      "discount_amount_excluding_vat": "0.0",
      "vat_percent": "0.25",
      "currency_code": "DKK"
    },
    {
      "line_type": "shipping",
      "item_name": "PostNord Shipping",
      "item_sku": null,
      "item_variant_code": null,
      "quantity": "1.0",
      "unit_price_excluding_vat": "80.0",
      "discount_amount_excluding_vat": "0.0",
      "vat_percent": "0.25",
      "currency_code": "DKK"
    }
  ]
}