Available APIs

Authentication - OAuth2.0

Orders

Inventory

Items

Inbound Shipments

Rmas

Labels

Receipt

Location

Tracking

Document

Webhook

Appointment

Troubleshooting

Create Order

This API creates a new order for fulfillment within the FedEx® Fulfillment platform. Once the order is submitted, it will be processed and sent to one or more warehouses for fulfillment based on business rules and inventory availability.

Swagger

			
swagger: '2.0'
info:
  x-ibm-name: orders
  title: Orders
  version: 1.0.0
schemes:
  - https
host: $(catalog.host)
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  oauth2:
    type: oauth2
    description: ''
    flow: accessCode
    authorizationUrl: 'https://<.........................>/fsc/oauth2/authorize'
    scopes:
      Fulfillment_Returns: ''
    tokenUrl: 'https://<.........................>/fsc/oauth2/token'
  Client_Secret:
    type: apiKey
    description: Enter Client Secret
    in: header
    name: X-IBM-Client-Secret
  Client_Id:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
    description: Enter Client ID
security:
  - Client_Secret: []
    Client_Id: []
    oauth2:
      - Fulfillment_Returns
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /orders:
    post:
      responses:
        200:
          description: 200 OK
      parameters:
      - name: create_order_json_body
        required: true
        in: body
        schema:
          type: json
        description: ''
      - name: AccessToken
        type: string
        required: true
        in: header
        description: Enter Access Token, it is required header
      	summary: Create Order
      	description: Creates a new Order for fulfillment within the Fulfillment portal.
        Once the order is submitted, it will be processed and sent to one or more
        warehouses for fulfillment based on business rules and inventory availability.

Sample Request

         

{
  "order": {
    "orderNumber": "091167792",
    "externalOrderNumber": "CAAMZ67792",
    "orderDate": "2017-01-20T15:12:54-05:00",
    "orderType": "B2C",
    "shipMethod": "FSON",
    "estimatedDeliveryDate": "2017-08-15",
    "shipType": "PCL",
    "salesChannel": "BigCommerce",
    "holdUntilDate": "2017-02-15T00:00:00-05:00",
    "facility": "HFY",
    "freightCost": "23.50",
    "insuranceCost": "10",
    "dutiesAndTaxes": "11.67",
    "alternatePackaging": true,
    "excludeCollateral": true,
    "accessorial": [
      "COA",
      "SAT",
      "DVL"
    ],
    "dropShip": true,
    "externalRefIds": [
      {
        "idKey": "marketplaceId",
        "idValue": "453"
      },
      {
        "idKey": "vendorId",
        "idValue": "V234"
      },
      {
        "idKey": "tradingPartnerId",
        "idValue": "TP435"
      }
    ],
    "destinationAddress": {
      "company": "Smith & Sons Inc.",
      "name": "James Smith",
      "addressLine1": "100 Papercraft Avenue",
      "addressLine2": "Suite 300",
      "city": "Pittsburgh",
      "stateCode": "PA",
      "zipCode": "15238",
      "countryCode": "US",
      "email": "abc@gmail.com",
      "sendTrackingNumber": true,
      "phoneNumber": "888-787-8888",
      "shipToLocNumber": "433223",
      "storeNumber": "545423"
    },
    "orderNote": [
      {
        "noteCode": "NOTES",
        "noteText": "This is a test order"
      },
      {
        "noteCode": "GIFT_FROM",
        "noteText": "Joseph"
      },
      {
        "noteCode": "GIFT_TO",
        "noteText": "Johnson"
      },
      {
        "noteCode": "GIFT_MSG",
        "noteText": "Happy Birthday!!"
      }
    ],
    "line": [
      {
        "externalLineId": "001",
        "sku": "003-003-0001111",
        "skuDescripton": "Mens Oxford (Small/Blue/Slim)",
        "unitPrice": "2.56",
        "orderedQty": "2",
        "orderedQtyUoM":"CA",
        "vendorSku": "TGTMEN0111",
        "upc": "614141000883",
        "gtin": "50614141000994"
      },
      {
        "externalLineId": "002",
        "sku": "005-001-0001",
        "skuDescription": "Fancy T-Shirt",
        "unitPrice": "2.56",
        "orderedQty": "2",
        "orderedQtyUoM":"CA",
        "vendorSku": "TGTMEN0133",
        "upc": "614141000012",
        "gtin": "00614141000029"
      }
    ]
  }
}

Sample Response

Success Response

         
{
   "requestIdentifier": "01749ea2-4b8f-4f3d-a9dc-f0b862a3d72e",
   "transactionDate": "2017-01-20T15:12:54-05:00",
  "success": "true",
  "order": {
    "orderNumber": "091167792",
    "fedexOrderId": "0001-0007-H0120173742",
    "orderStatus": "Held"
  }
}

Error Response

      
{
   "requestIdentifier": "01749ea2-4b8f-4f3d-a9dc-f0b862a3d72e",
   "transactionDate": "2017-01-20T15:12:54-05:00",
  "success": "false",
  "errors": [
    {
      "code": "ERR-ORD-0004",
      "description": "Order arrived with missing or invalid SKU"
    }
  ]
}

OAuth 2.0

HTTP Headers Description
Authorization You must always provide the access token for authorization to access the API.

HTTP-Header       Value
Authorization       Bearer accessToken
Origin Origin URL.

HTTP-Header       Value
Origin                domain.com

Custom authentication

HTTP Headers Description
X-IBM-Client-Id You must always provide in the HTTP header your API portal application's client ID (X-IBM-Client-Id) to access the API.

HTTP-Header       Value
X-IBM-Client-Id     ************
X-IBM-Client-Secret You must always provide in the HTTP header your API portal application's client secret (X-IBM-Client-Secret) to access the API.

HTTP-Header       Value
X-IBM-Client-Secret     ************
AccessToken Application Access Token
Origin Origin URL.

HTTP-Header       Value
Origin                domain.com

Request Attribute

Parameter Data Type Description Required
order      
orderNumber String(Alphanumeric) Channel order ID.

Special characters allowed:

hyphen(-)
underscore(_)
hash(#)
space
tab		 Y
externalOrderNumber String External Order Number that represents customer order number or marketplace order number.

Mandatory for Amazon Prime orders. (i.e. shipMethod='ASFP')

 Y (when shipMethod = 'ASFP')
N – all other scenarios
orderDate String Ordered date/time (ISO8601 format)
Format: 2016-09-21T14:30:59-05:00		 N
orderType String(Alphanumeric) Order type. If not provided, the value will default to B2C
Valid Values: B2C, B2B and any custom order types set up in the API Developer Portal or Retailer specific custom order type codes.See list below for the custom order type codes		 N
shipType String Shipment type
Valid Values: PCL, LTL.
• PCL - Parcel
• LTL - Less than Truck Load		 Y
shipMethod String(Alphanumeric) Shipment method. Applicable for Shipment Type PCL.
Valid Values: See list below in Shipment methods.		 Y (when shipType = PCL)
N (when shipType = LTL)
estimatedDeliveryDate String(UTC format) Estimated date for the shipment to get delivered to the customer. This is applicable if service level code is specified in the ship method field.
Format:YYYY-MM-DD		 N
estimatedShipDate String Estimated ship date/time for order.

date/time (ISO8601 format).
Format:2016-09-21T14:30:59-05:00		 N
salesChannel String(Alphanumeric) Sales channel where the order was created.

Special characters allowed:

hyphen(-)
underscore(_)
hash(#)
brackets "(){}[]"
space
tab
apostrophe(')		 N
holdUntilDate String(UTC format) The order will be held until the date/time specified. Order will be released for fulfillment after that.
If the date is not provided, order will be released depending on Grace period settings.		 N
facility String(Alphanumeric) Fulfillment facility for the order.
Valid values: HFY, FCA
• HFY - Greenwood, IN
• FCA - Fontana, CA		 N
freightCost String(Decimal) Freight cost. Applicable for international orders N
insuranceCost String(Decimal) Insurance cost. Applicable for international orders N
dutiesAndTaxes String(Decimal) Duties and Taxes. Applicable for international orders N
alternatePackaging Boolean Indicates whether the saved order packaging options will NOT be applied to this order.
Valid Values: true or false.		 N
excludeCollateral Boolean Indicates whether the related collateral rules will be overridden, and all collateral will be excluded from this order.
Valid Values: true or false.		 N
accessorial[] String Indicates accessorial information for the order. It can be an array of multiple codes, however, out of the signature options COA/COS, only one should be passed.
Valid Values: COA, COS, SAT
• COA - Adult Signature Required
• COS - Direct Signature Required
• SAT - Saturday Delivery
See below for accessorial eligibility with
Shipment methods and Service Levels		 N
dropShip Boolean Indicates whether this is a drop ship order.
Valid Values: true or false.		 N
order.externalRefIds[]      
idKey String Key for the Key/Value pair for the external reference Ids.
Valid Values:vendorId, tradingPartnerId, marketplaceId.
See definitions below in External Ref Ids definitions		 N
idValue String Value for the Key/Value pair for the external reference Ids. N
order.destinationAddress      
company String Name of the Company. N
name String Name of the recipient

Special characters allowed:

apostrophe (')
hyphen(-)
brackets "(){}[]"
space
tab		 Y
addressLine1 String Address Line 1

Special characters allowed:

apostrophe (')
hyphen(-)
brackets "(){}[]"
space
tab		 Y
addressLine2 String Address Line 2

Special characters allowed:

apostrophe (')
hyphen(-)
brackets "(){}[]"
space
tab		 N
city String City

Special characters allowed:

apostrophe (')
hyphen(-)
brackets "(){}[]"
space
tab		 Y
stateCode String State code Y
zipCode String(Alphanumeric) Zip code


Special characters allowed:

hyphen(-)
space
For US:
5 numeric digits (or)
5 numeric digit, hyphen(-), 4 numeric digits		 Y
countryCode String(Alphanumeric) Country code Y
email String(Alphanumeric) Recipient email address

Special characters allowed:

at(@)
hyphen(-)
dot (.)
underscore(_)
plus (+)		 N
sendTrackingNumber Boolean Indicates whether E-mail id is present in order request.
Valid Values: true or false.		 N
phoneNumber String(Alphanumeric) Recipient phone number

Special characters allowed:

hyphen(-)
open bracket "("
close bracket ")"
dot (.)
space
tab
plus (+)		 Y
shipToLocNumber String Ship to Location Number or Distribution Center Number that shipment is being sent to. N
storeNumber String Store Number or Ultimate Destination Number when a shipment is sent to a DC but needs to be marked / packed for a specific location. N
order.orderNote[]      
noteCode String Code to indicate the type of information sent in the note text field
Valid Values:
NOTES
GIFT_FROM
GIFT_TO
GIFT_MSG		 Y (if noteText is provided)
noteText String(Alphanumeric) Text note for the respective note code associated with the order.

Special characters allowed:

apostrophe (')
hyphen(-)
brackets "(){}[]"
space
tab		 N
order.line[]      
externalLineId String External line identifier N
sku String(Alphanumeric) SKU of the product (case sensitive)

Special characters allowed:

apostrophe(')
dot(.)
hash(#)
hyphen(-)
space
tab
underscore(_)		 Y
skuDescription String(Alphanumeric) Product description

Special characters allowed:

apostrophe(')
dot(.)
hash(#)
hyphen(-)
space
tab
underscore(_)		 N
unitPrice String Product unit/retail price N
orderedQty String(Decimal) Ordered quantity Y
orderedQtyUoM String Ordered quantity unit of measure.
Valid Values: EA, CA, PA.
• EA – Eaches/Units (default)
• CA - Case
• PA - Pallet		 N
vendorSku String SKU identifier at vendor side. N
upc String Universal product code for the item, if it is marked with a bar code. N
gtin String Global Trade Item Number for the item. N

Response Attribute

Parameter Data Type Description
requestIdentifier String Request identifier
transactionDate String Transaction date/time
success String Status of the transaction
Valid Values:
true or false.
order    
orderNumber String(Alphanumeric) Channel order number

Special characters allowed:

hyphen(-)
underscore(_)
hash(#)
space
tab
fedexOrderId String(Alphanumeric) FedEx order ID generated by the system
Special characters allowed:
hyphen(-)
orderStatus String Status of the order
errors[]    
code String Code associated with the error
description String Description of the error

HTTP Status Code

Code Description
200 OK - HTTP Response for successfully processed requests
400 Bad Request.
403 Forbidden
404 Not Found - Server couldn’t find anything matching request URI
500 Internal Server Error – Unable to process the request

Error Code

Code Description
ERR-SYS-0001 Your request cannot be processed due to a system error.
ERR-CMR-0001 Input data validation failed.
ERR-CMR-0002 Authentication Failed. Invalid Access Token.
ERR-CMR-0003 Missing mandatory fields.
ERR-ORD-0001 Channel Order Id (orderNumber) is missing
ERR-ORD-0002 Order Date - Invalid format
ERR-ORD-0003 SKU is missing
ERR-ORD-0004 Order arrived with missing or invalid SKU
ERR-ORD-0005 Item quantity is missing
ERR-ORD-0006 Quantity value is invalid
ERR-ORD-0007 Retail price is invalid
ERR-ORD-0008 Name is missing
ERR-ORD-0009 Address Line 1 is missing
ERR-ORD-0010 City is missing
ERR-ORD-0011 State code is missing
ERR-ORD-0012 Zip code is missing
ERR-ORD-0013 Country code is missing
ERR-ORD-0014 Invalid e-mail address
ERR-ORD-0015 Missing phone number
ERR-ORD-0016 Invalid delivery type
ERR-ORD-0017 Shipping type is missing
ERR-ORD-0018 Invalid shipping type value
ERR-ORD-0019 Shipping method is missing
ERR-ORD-0020 Invalid shipping method value
ERR-ORD-0021 Client ID is missing
ERR-ORD-0022 Order already exists
ERR-ORD-0023 SKU does not exist
ERR-ORD-0024 Order does not exist
ERR-ORD-0025 Order cannot be updated. Order is being processed or already shipped
ERR-ORD-0026 Order cannot be canceled. Order is being processed or already shipped
ERR-ORD-0027 Cancel reason code is missing or invalid
ERR-ORD-0028 Order arrived with a non-US country code. International orders are not allowed through this API call
ERR-ORD-0029 Request cannot be processed with more than 25 orders in the filter.
ERR-ORD-0030 Sales channel and order number should be used together to filter the orders by Sales channel.
ERR-ORD-0031 FedEx order ID and Order Number cannot be used together to filter the orders.
ERR-ORD-0032 Time stamp filter is not in the required format.
ERR-ORD-0033 Time stamp and condition type should be used together to filter orders based on Timestamp
ERR-ORD-0034 Invalid Condition type value
ERR-ORD-0035 Invalid response filter value
ERR-ORD-0037 Order arrived with inactive SKU
ERR-ORD-0043 Order has an invalid address.
ERR-ORD-0044 Order address could not be validated. System will automatically reprocess in a few minutes.
ERR-ORD-0046 Connection is inactive
ERR-ORD-0047 Hold until date cannot be in the past
ERR-ORD-0051 Search criteria did not return any results
ERR-ORD-0052 Hold until date - Invalid format
ERR-ORD-0054 International shipping is not enabled
ERR-ORD-0055 Order contains some SKUs with missing information that is mandatory for International shipping
ERR-ORD-0056 Invalid facility code
ERR-ORD-0057 Invalid country code
ERR-ORD-0058 Freight costs are in invalid format
ERR-ORD-0059 Insurance costs are in invalid format
ERR-ORD-0060 Duties and taxes are in invalid format
ERR-ORD-0061 Invalid order type
ERR-ORD-0062 The destination email address is required when the sendTrackingNumber is true.
ERR-ORD-0063 Note code is invalid or missing.
ERR-ORD-0064 Invalid estimated delivery date.
ERR-ORD-0065 Invalid Accessorial code.
ERR-ORD-0066 Accessorial code not applicable for the Shipping method provided.
ERR-ORD-0067 Invalid Order type and Drop ship combination
ERR-ORD-0068 Amazon connection information missing or inactive
ERR-ORD-0069 Invalid Ordered Qty Unit of Measure.
ERR-ORD-0070 External order number is required for Seller Fulfilled Prime orders.
ERR-ORD-0071 Invalid External Reference Id.
ERR-ORD-0072 External Reference Id Value is missing.
ERR-ORD-0073 Invalid Ordered Qty Unit of Measure and Order Type combination.
ERR-ORD-0074 Invalid Ordered Qty Unit of Measure and Facility combination.

Shipment Methods

Countries Shipping Method Code Accessorials Eligible
United States FedEx SmartPost FXPP -
FedEx Home Delivery FXHD COA, COS
FedEx Ground FXGD COA, COS
FedEx Express Saver FEXS COA, COS
FedEx 2Day F2DY COA, COS, SAT
FedEx Priority Overnight FPON COA, COS, SAT
FedEx Standard Overnight FSON COA, COS
Amazon Seller Fulfilled Prime ASFP COA, COS, SAT
Canada FedEx International Ground® FV COA, COS
FedEx International Priority® FIP COA, COS, SAT
FedEx International Economy® FIE COA, COS
All countries except US and Canada FedEx International Priority FIP COA, COS, SAT
FedEx International Economy FIE COA, COS

Shipment service levels

Service Level Code Default est. delivery days Services Included Accessorials Eligible
Value VALU 10 FedEx Ground®
FedEx Home Delivery®
FedEx SmartPost®		 -
Value with Signature VALS 10 FedEx Ground
FedEx Home Delivery		 COA, COS
Standard STRD 5 FedEx 2Day®
FedEx Express Saver®
FedEx Ground
FedEx Home Delivery
FedEx SmartPost
FedEx Standard Overnight®		 -
Standard with Signature STRS 5 FedEx Ground
FedEx Home Delivery
FedEx Express Saver
FedEx 2Day
FedEx Standard Overnight		 COA, COS
Expedited EXPD 3 FedEx 2Day
FedEx Express Saver
FedEx Ground
FedEx Home Delivery
FedEx SmartPost
FedEx Standard Overnight		 -
Expedited with Signature EXPS 3 FedEx Ground
FedEx Home Delivery
FedEx Express Saver
FedEx 2Day
FedEx SmartPost
FedEx Standard Overnight		 COA, COS
2 Day 2DAY 2 FedEx 2Day
FedEx Express Saver
FedEx Ground
FedEx Home Delivery
FedEx Standard Overnight		 COA, COS
Overnight OVRN 1 FedEx Ground
FedEx Home Delivery
FedEx Standard Overnight		 COA, COS
    FEDEX WITH USPS    
ValuewUSPS FUVL 10 FedEx Ground
FedEx Home Delivery
FedEx SmartPost
USPS First Class
USPS Parcel Select
USPS Priority Mail		 -
ValuewUSPS with Signature FUVS 10 FedEx Ground
FedEx Home Delivery
USPS Priority Mail
USPS First Class
USPS Parcel Select		 COA, COS
StandardwUSPS FUST 5 FedEx 2Day
FedEx Express Saver
FedEx Ground
FedEx Home Delivery
FedEx SmartPost
FedEx Standard Overnight
USPS First Class
USPS Parcel Select
USPS Priority Mail		 COA, COS
StandardwUSPS with Signature FUSS 5 FedEx Ground
FedEx Home Delivery
FedEx Express Saver
FedEx 2Day
FedEx Standard Overnight
USPS Priority Mail
USPS First Class
USPS Parcel Select		 COA, COS
ExpeditedwUSPS FUED 3 FedEx 2Day
FedEx Express Saver
FedEx Ground
FedEx Home Delivery
FedEx SmartPost
FedEx Standard Overnight
USPS First Class
USPS Parcel Select
USPS Priority Mail		 -
ExpeditedwUSPS with Signature FUES 3 FedEx Ground
FedEx Home Delivery
FedEx Express Saver
FedEx 2Day
FedEx Standard Overnight
USPS Priority Mail
USPS First Class
USPS Parcel Select FedEx 2Day		 COA, COS
2 DaywUSPS FU2D 2 FedEx 2Day
FedEx Express Saver
FedEx Ground
FedEx Home Delivery
FedEx Standard Overnight
USPS Parcel Select
USPS Priority Mail
USPS Priority Mail Express		 COA, COS
OvernightwUSPS FUON 1 FedEx Ground
FedEx Home Delivery
FedEx Standard Overnight
USPS Priority Mail Express		 COA, COS
    USPS    
USPSStandard USTD 10 USPS First Class
USPS Parcel Select
USPS Priority Mail		 COA, COS
USPSExpedited UEXD 3 USPS First Class
USPS Parcel Select
USPS Priority Mail
USPS Priority Mail Express		 COA, COS
USPS2 Day U2DY 2 USPS Parcel Select
USPS Priority Mail
USPS Priority Mail Express		 COA, COS
USPSOvernight UOVN 1 USPS Priority Mail Express COA, COS

Retailer specific custom order type codes

Custom Order Type Code Retailer
101 Kohl's
102 Bed Bath & Beyond
103 Costco
104 CVS.com
105 Jet.com
106 Best Buy US
108 Buy Buy Baby
112 Best Buy Canada

External Reference Id Keys

order[].externalRefIds[].idKey Description
marketplaceId Partner internal identifier to represent marketplace
tradingPartnerId Partner internal identifier to represent the relationship of the retailer with vendor/buyer
vendorId Partner internal identifier assigned to represent vendor