Fulfillment API

POST /orders Create Order

API version V1.2

Please note:

content-type is required although it shows optional

Additional information and instructions.

FMS only
Some sections below are marked as FMS-Only. These sections only apply when ModusLink is handling payments.

Date-time format
The date-time format used in request and response is UTC using the ISO 8601 format : yyyy-mm-ddThh:mm:ssZ, e.g. 2018-12-19T15:58:00Z
All date-time values should follow this format and should have UTC time without offset.

Example:
An order is posted from the Netherlands where the timezone is UTC+1. If the local timestamp would be 2018-12-19T15:58:00+01:00 the value provided would be the UTC time, 2018-12-19T14:58:00Z

Shipping info

ModusLink typically will do a dynamic carrier determination based on an agreed freight matrix, and the destination and total weight/volume of each order.The order can contain information about shipping options. The following input parameters are used to provide this information:

shipServiceLevel
- This will provide the service level applicable to the order. The possible values depend on the agreed requirements. The following values are available:
  - ECO – economy shipment
  - STD – standard shipment
  - EXP – express shipment
  - PUD – Pick Up or Drop Off
IncoTerm
- The incomterm to be used, per Incoterms 2010 Standard. Possible values are CPT, DDP, DAP, FCA, EXW etc. Applicable values will need to be agreed between ModusLink and the client.

Multi-site fulfillment:

multiple CCID’s
In case fulfillment is done from multiple locations e.g. different regions, ModusLink will provide the client with multiple CCID’s. One for each location/region. Another reason for multiple CCID ‘s can be to differentiate between sales channels/streams like B2C and B2B orders or Web and Contact Center orders.

e.g. shipping from Netherlands and Singapore
In this case 2 CCID’s would be provided. When making a call to the API the appropriate CCID and region would have to be provided.

Shipping

For Shipping costs a separate line item should be added to the order. This order item will have a fixed sku e.g. [ClientCode]_SHIPCOSTS, which will be provided by ModusLink. The price of the item will represent the shipping costs. If no shipcosts apply this item can be omitted.

amount types

Amount types are used as below:

Order Header Amounts:

totalNet - The total net amount of the order
totalTax - The total tax amount of the order
totalGross - The total gross amount of the order (net plus tax)

Payment Amounts:

paid - the paid amount
authorized - the authorized amount
created - the created amount

Order Item Amounts:

netPrice - the net price of the item
grossPrice - the gross price of the item
exportPrice - the commercial value of the goods for Export

The expectation is that for B2C gross pricing will be used, and for B2B net pricing. ModusLink can accommodate both models, but the model is fixed for a CCID, and needs to be agreed upon upfront.

Special Cases

Item discount (FMS-Only)
Pricing for the item should be the discounted item price. Original price minus discount applied.

Order discount (FMS-Only)
When a discount is applied to the order. Add a discount item to the order message, with negative value for the item, representing the discount value, see below sample. The SKU will be fixed and provided by Moduslink

  {
    "itemId": "1", 
    "clientItemRef":"",
    "sku": "CLIENT_DISCOUNT",
    "quantity": {
    "uom": "EA",
    "value": “1”
    },
    "amount": [
      {
        "currencyISO3":"USD",
        "amountType":"grossPrice",
        “value": "-105.00”
      },
      {
        "currencyISO3":"USD",
        "amountType":"netPrice",
        “value": "-100”
      }
    ],
    "taxLevel":"HIGH",
    "taxFactor":"1.05",
    "pricing":"grosspricing",
    "localizedDescription":"Localised description",
    "dynamicField": [
      {
        "name":"SkuDescription",
        "value": “SkuDescription”
      }
    ]
  }

WEEE (FMS-Only)
WEEE refers to any charges related to European Community Directive 2012/19/EU on waste electrical and electronic equipment (WEEE). It is a fee levied to facilitate recycling of electronic and electric equipment. When ModusLink provides Financial Management Services (payment processing, invoicing, bank account management, credit and collection etc.), ModusLink will take care of the required WEEE fee submissions and reporting.

Add an additional line item to the order to hold the WEEE fee for the item. Each item that has a WEEE fee, needs an associated WEEE item. Therefore the order can have multiple WEEE items. Each WEEE item will have the same sku but a different localised description. Then the WEEE fee item can be associated with a product line in the order. See sample below:

  {
     "itemId": "1",
     "clientItemRef":"",
     "sku": "[ClientCode_WEEE]",
     "quantity": {
       "uom": "EA",
       "value": “1”
      },
     "amount": [
     {
       "currencyISO3":"USD",
       "amountType":"grossPrice",
       “value": "1.50”
     },
     {
       "currencyISO3":"USD",
       "amountType":"netPrice",
       “value": "1.25”
     }
    ],
    "taxLevel":"HIGH",
    "taxFactor":"1.20",
    "pricing":"grosspricing",
    "localizedDescription":"WEEE [<>]",
    "dynamicField": []
  }

SKU - The partnumber to which this WEEE fee applies
[ClientCode_WEEE] -The WEEE part number provided to you by ModusLink.

Codice Fiscali (FMS-Only)
For Italian orders the webstore needs to get the clients fiscal code and add this to the order as an order dynamic field.

Field		Value
order-dynamicField-name		FISCAL_CODE
order-dynamicField-value		fiscall code provided

e-Invoicing (FMS-Only)
For localisation of invoices the order needs to provide the local to be used. E.g. the language used to create the order online. This will drive the language of the e-invoice. partner-personData-locale

format		LanguageCode-CountryCode
sample		nl-NL

Payment Review (FMS-Only)
In case the payment result is review required this needs to be added to the order as order dynamic fields.

Field		Value
order-dynamicField-name		PROCESSAUTHSTATUS
order-dynamicField-value		Review
order-dynamicField-name		PROCESSAUTHSTATUSCODE
order-dynamicField-value		DM_REVIEW

Export FOC orders
In case of export outside the EU the price elements should always (also with Free Of Charge or Fulfillment Only orders) contain a value amount of the product at the Item level. This export price is printed on the Customs/Commercial Invoice. The gross price may contain zero value (in case of a Free of Charge product).

As a general guideline for export Price:

For end user paying B2C orders – always commercial value (net price)
For end user free of charge or sample shipments – fill with the “transfer” value or equivalent, i.e. standard inventory value.
For B2B users where you as our client are the IOR – use the transfer value
For B2B customers where your customer is IOR – use full commercial value

See below line item amount sample.

  {
    "amount": [
      {
        "currencyISO3":"USD",
        "amountType":"grossPrice",
        "value": “0.00”
      },
      {
        "currencyISO3":"USD",
        "amountType":"netPrice",
        "value": “125”
      },
      {
        "currencyISO3":"USD",
        "amountType":"exportPrice",
        "value": “125”
      }
    ],

Bundles
For bundles Moduslink will receive the underlying items of the bundle in the order message. For example:
Bundle_A containing the following items:
    Item: SKU_A qty in bundle: 1
    Item: SKU_B qty in bundle: 2

The item price in the order message should be the original item price minus the bundle discount applied:
    SKU_A has item price: 10.00
    SKU_B has item price: 20.00
    Bundle_A has a price of: 44.00

The bundle is sold for 44 instead of 50, the 6 discount applied to the bundle, should be split accross the two items in the bundle, and sent as such in the order message:
Based on the sample bundle, the order message will include, the following items and prices:
    SKU_A with qty 1 and item price: 8.80
    SKU_B with qty 2 and item price: 17.60

Billing option
For B2B customers. In case they want to provide the freight billing option, this can be done by adding a dynamic field with the following detail: Valid values are:

0 - DEFAULT
1 - PREPAID CLIENT
2 - PREPAID ML A/C
3 - 3RD PARTY CLIENT
4 - 3RD PARTY ML
5 - COLLECT CLIENT
6 - COLLECT ML
7 - PREPAID AND ADD
8 - CONSIGNEE

Field		Value
order-dynamicField-name		BIL_OPT
order-dynamicField-value		the applicable billing option

GET /orders Retrieve Orders
API version V1.2

Additional information and instructions.

Date-time format
The date-time format used in request and response is UTC using the ISO 8601 format : yyyy-mm-ddThh:mm:ssZ, e.g. 2018-12-19T15:58:00Z
All date-time values should follow this format and should have UTC time without offset.

Example:
An order is posted from the Netherlands where the timezone is UTC+1. If the local timestamp would be 2018-12-19T15:58:00+01:00 the value provided would be the UTC time, 2018-12-19T14:58:00Z

amount types

Amount types are used as below:

Order Header Amounts:
- totalNet - The total net amount of the order
- totalTax - The total tax amount of the order
- totalGross - The total gross amount of the order (net plus tax)
Payment Amounts:
- paid - the paid amount
- authorized - the authorized amount
- created - the created amount
Order Item Amounts:
- netPrice - the net price of the item
- grossPrice - the gross price of the item
- exportPrice - the commercial value of the goods for Export
The expectation is that for B2C gross pricing will be used, and for B2B net pricing. ModusLink can accommodate both models, but the model is fixed for a CCID, and needs to be agreed upon upfront.
GET /orders/{requestId} Retrieve Order
API version V1.2

Additional information and instructions.

Date-time format
The date-time format used in request and response is UTC using the ISO 8601 format : yyyy-mm-ddThh:mm:ssZ, e.g. 2018-12-19T15:58:00Z
All date-time values should follow this format and should have UTC time without offset.

Example:
An order is posted from the Netherlands where the timezone is UTC+1. If the local timestamp would be 2018-12-19T15:58:00+01:00 the value provided would be the UTC time, 2018-12-19T14:58:00Z

amount types

Amount types are used as below:

Order Header Amounts:
- totalNet - The total net amount of the order
- totalTax - The total tax amount of the order
- totalGross - The total gross amount of the order (net plus tax)
Payment Amounts:
- paid - the paid amount
- authorized - the authorized amount
- created - the created amount
Order Item Amounts:
- netPrice - the net price of the item
- grossPrice - the gross price of the item
- exportPrice - the commercial value of the goods for Export
The expectation is that for B2C gross pricing will be used, and for B2B net pricing. ModusLink can accommodate both models, but the model is fixed for a CCID, and needs to be agreed upon upfront.
POST /rmas Create RMA

API version V1.2
Additional information not available.
GET /rmas Retrieve RMAs
API version V1.2

Additional information and instructions.

Date-time format
The date-time format used in request and response is UTC using the ISO 8601 format : yyyy-mm-ddThh:mm:ssZ, e.g. 2018-12-19T15:58:00Z
All date-time values should follow this format and should have UTC time without offset.

Example:
An RMA is posted from the Netherlands where the timezone is UTC+1. If the local timestamp would be 2018-12-19T15:58:00+01:00 the value provided would be the UTC time, 2018-12-19T14:58:00Z

amount types

Amount types are used as below:

Payment Amounts:
- paid - the paid amount
- authorized - the authorized amount
- created - the created amount
RMA Item Amounts:
- netPrice - the net price of the item
- grossPrice - the gross price of the item
GET /rmas/{requestId} Retrieve RMA
API version V1.2

Additional information and instructions.

Date-time format
The date-time format used in request and response is UTC using the ISO 8601 format : yyyy-mm-ddThh:mm:ssZ, e.g. 2018-12-19T15:58:00Z
All date-time values should follow this format and should have UTC time without offset.

Example:
An RMA is posted from the Netherlands where the timezone is UTC+1. If the local timestamp would be 2018-12-19T15:58:00+01:00 the value provided would be the UTC time, 2018-12-19T14:58:00Z

amount types

Amount types are used as below:

Payment Amounts:
- paid - the paid amount
- authorized - the authorized amount
- created - the created amount
RMA Item Amounts:
- netPrice - the net price of the item
- grossPrice - the gross price of the item

POST /orders Create Order

API version V1.2

Please note:

Additional information and instructions.

Shipping info

Multi-site fulfillment:

Shipping

amount types

Special Cases

GET /orders Retrieve Orders

API version V1.2

Additional information and instructions.

amount types

GET /orders/{requestId} Retrieve Order

API version V1.2

Additional information and instructions.

amount types

POST /rmas Create RMA

API version V1.2

GET /rmas Retrieve RMAs

API version V1.2

Additional information and instructions.

amount types

GET /rmas/{requestId} Retrieve RMA

API version V1.2

Additional information and instructions.

amount types