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