Available APIs
Authentication - OAuth2.0
Inventory
Items
Inbound Shipments
Labels
Receipt
Location
Tracking
Document
Create Item
The Items API provides the capability of creating new products within the FedEx® Fulfillment platform. These newly created products will be part of Product Catalog for the retailer to manage their inventory and make any required changes to an existing product information.
Swagger
swagger: '2.0'
info:
x-ibm-name: items
title: Items
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/oauth/authorize'
scopes:
Fulfillment_Returns: ''
tokenUrl: 'https://<.....................>/fsc/oauth/token'
x-tokenIntrospect:
url: 'https://<.....................>/fsc/oauth/introspect'
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_Id: []
Client_Secret: []
oauth2:
- Fulfillment_Returns
x-ibm-configuration:
testable: true
enforced: true
phase: realized
paths:
/items:
post:
responses:
200:
description: 200 OK
parameters:
- name: input_request
required: false
in: body
schema:
type: object
description: "Items API provides the capability of creating new products within Commerce Portal. These newly created products will be part of Product Catalog for the Retailer to manage their Inventory and make any required changes to an existing product information."
tags: []
consumes:
- application/json
- text/plain
produces:
- application/json
Sample Request
{
"item" : {
"dscription" : "Test Item",
"longDescription" : "Test ",
"hsCode" : "1040.60",
"brand" : "Apple",
"model" : "Apple",
"subCategory" : "Laptop",
"productClass" : "Class",
"retailerType" : "RMS",
"hazardMaterial" : false,
"battery" : true,
"batteryType" : "Alkaline",
"barCodeMarked" : true,
"shelfLife" : 35,
"serializationRequired" : true,
"batchLotRequired" : false,
"polyBagRequired" : true,
"shipAlone" : false,
"internationalShipping" : true,
"countryCode" : "US",
"fragile" : true,
"perishable" : true,
"liquid" : true,
"sku" : "SKU123",
"upc" : "423445656321",
"size" : "Large",
"style" : "Skinny",
"color" : "Red",
"dimensions" : {
"height" : 12,
"length" : 10,
"width" : 1
},
"weight" : 1.2,
"itemCost" : 1,
"retailPrice" : 34.43,
"returnItemInfo" : {
"returnable" : true,
"returnDaysLimit" : 4,
"destination" : "RET",
"shippingService" : "GR",
"serialNumber" : true,
"requireRepCapture" : false,
"countryOfOriginRequired" : true,
"casPackingSku" : [{
"packingSku" : "12345"
}, {
"packingSku" : "23456"
}, {
"packingSku" : "78965"
}
]
},
"lowStockThreshold" : 10,
"hazardous" : 1,
"name" : "qw",
"categoryId" : 1,
"variants" : [{
"attributeKey" : "length",
"attributeValue" : "453"
}, {
"attributeKey" : "multicolor",
"attributeValue" : "444"
}, {
"attributeKey" : "testproduct",
"attributeValue" : "22"
}
],
"caseDetails" : [{
"caseType" : "case",
"barCode" : "12332234",
"height" : 12.2,
"length" : 1,
"width" : 12.23,
"weight" : 12.4,
"numberOfUnits" : 1
}, {
"caseType" : "pallet",
"barCode" : "12332234222",
"height" : 12.2,
"length" : 1,
"width" : 45.2,
"weight" : 2.4,
"numberOfUnits" : 2
}
]
}
}
Sample Response
Success Response
{
"requestIdentifier" : "739d28b6-269c-11e7-9a3d-0ac443290000",
"transactionDate" : "2017-04-21T10:11:45-04:00",
"success" : "true",
"items" : {
"itemId" : 311103,
"sku" : "SKU1-23-SKU-234-S12w4443r"
}
}
Error Response
{
"requestIdentifier" : "ff8ce974-26a6-11e7-9a3d-0ac443290000",
"transactionDate" : "2017-04-21T11:27:15-04:00",
"success" : "false",
"errors" : [{
"code" : "ERR-PDT-0002",
"description" : "Product (ITEM_SKU) is already exist"
}
]
}
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 |
|---|---|---|---|
| weight | Number | Weight of an individual item, in pounds, to the nearest hundredth of a pound. | Y |
| lowStockThreshold | Number | Low stock threshold for the item.Number of units that will trigger an alert when the inventory goes below the value entered. Valid Values: 5, 10, 25, 50, 100 | N |
| sku | String | Item code or SKU. This code is unique to the item and is used for stock-keeping purposes. | Y |
| upc | String | Universal product code for the item, if it is marked with a bar code. The fulfillment center can use this information for inventory tracking. |
Y (Only for returns) |
| itemCost | Number | Cost of the item for your business. This information is used with reports. |
Y |
| retailPrice | Number | Retail price for the item. This information is used with reports and is printed on commercial invoices. |
Y |
| name | String | Short description for the catalog item, e.g., Rosemary Hand Balm. | Y |
| battery | Boolean | Indicates whether the item contains a battery. If you enter “true” you also need to provide an entry for battery type. |
Y |
| longDescription | String | Detailed description of the item. | N |
| fragile | Boolean | Indicates whether the item is fragile. If you enter “true,” additional fees may apply to handling this item. |
Y (Only for fulfillment) |
| hazardMaterial | Boolean | Indicates whether the item is hazardous. If the item is marked as “true,” speak to a customer success specialist before sending the item to the fulfillment center. |
Y |
| liquid | Boolean | Indicates whether the item contains liquid. | Y (Only for fulfillment) |
| perishable | Boolean | Indicates whether the item is prone to spoilage or decay. If you enter “true,” you also need to provide an entry for Shelf Life |
Y (Only for fulfillment) |
| categoryId | String | Category ID for this item. Valid Values:See the dropdown list for Category ID. ID NAME 1 Apparel & Accessories 2 Automotive 3 Books 4 Chemicals & Cleaners 5 Electronics 6 Food & Beverage 7 Health & Beauty 8 High Value 9 Hobbies 10 Houseware 11 Movies & Music 12 Nutraceuticals 13 Sports & Fitness 14 Toys 15 Others |
Y |
| barCodeMarked | Boolean | Indicates whether the item is marked with a bar_code. If the item is not marked with a bar code, additional processing fees may apply. |
Y (Only for fulfillment) |
| shelfLife | Number | The number of days prior to the product expiration date. Perishable products are not shipped if they are at their shelf life limit. |
N (Required only when perishable field = ‘Y’) |
| batteryType | String | Indicates the type of battery the item contains. Valid Values: Nickel Cadmium, Nickel-Metal Hydride, Lead Acid, Lithium Ion, Lithium Ion Polymer, Alkaline, Other. This information is used to determine what methods of shipment are possible within regulations for hazardous materials. |
N (Required only when battery field = ‘Y’) |
| serializationRequired | Boolean | Indicates whether the fulfillment center needs to track individual items by serial numbers on the item. If you enter “true,” additional fees may apply to handling this item. |
Y (Only for fulfillment) |
| batchLotRequired | Boolean | Indicates whether the item requires additional tracking by batch or lot number. If you enter “true,” additional fees may apply to handling this item. |
Y (Only for fulfillment) |
| polyBagRequired | Boolean | Indicates whether the item can ship in a polyurethane bag with no additional packaging. | Y (Only for fulfillment) |
| shipAlone | Boolean | Indicates whether the item can ship in its own packaging. | Y |
| internationalShipping | Boolean | Indicates whether the item can ship internationally. | N (Only for fulfillment) |
| countryCode | String | Two-digit country code. This entry is required if the item may be shipped internationally. Valid Values: See the table list for |
N (Required only when internationalShipping value = ‘Y’) (Only for fulfillment) |
| hsCode | String | 6-digit Harmonized System code. This entry is required if the item is shipped internationally. Example:1040.60 |
N (Required only when internationalShipping value = ‘Y’) (Only for fulfillment) |
| brand | String | Brand of the item,e.g.,Apple, DELL. | N |
| model | String | Model of the item. | N |
| subCategory | String | A subgroup of a category. Example:If Category = Electronics, Subcategory = Laptop. |
N |
| productClass | String | An identifier indicating how the specific product differs from the normal products, such as high dollar, special handling, etc. | N |
| size | String | Size of the product. Example – Medium. |
N |
| color | String | Color of the product. Example – Red. |
N |
| style | String | Style of the product. Example – Skinny. |
N |
| returnItemInfo | |||
| serialNumber | String | Indicates whether the item requires a serial number during the return process. | N |
| shippingService | String | Indicates whether special shipping is needed for returning the item. Valid Values: EX (FedEx® Express),GR (FedEx® Ground) If you leave this null, FedEx calculates for you. |
N |
| countryOfOriginRequired | Boolean | Indicates whether the country of origin is needed during the return process. | N |
| returnable | Boolean | Indicates whether the item can be returned after a sale. | Y |
| returnDaysLimit | Number | The number of days from original order date when the item is eligible for return. | N |
| destination | String | Indicates how the return item should be handled, e.g., Destroy, Salvage, Vendor Return. Valid Values: See the table list for |
Y (Only for returns) |
| requireRepCapture | Boolean | Indicates whether the item requires authorization during the return process. | N |
| casPackingSku[] Limit 3 | |||
| packingSku | String | The packing sku used for the item being returned. This is an array value. You can add up to three values within the array. The first will be marked as the primary SKU. |
N |
| Dimensions | |||
| height | Number | Height of the product in inches. If you choose to enter product dimensions, you must enter all three dimensions: – length, width and height – to avoid an error during upload. |
N |
| length | Number | Length of the product in inches. If you choose to enter product dimensions, you must enter all three dimensions –: length, width and height – to avoid an error during upload. |
N |
| width | Number | Width of the product in inches. If you choose to enter product dimensions, you must enter all three dimensions: – length, width and height – to avoid an error during upload. |
N |
| Variants[] - Indicates the variant attributes for the product Limit 3 | N | ||
| attributeKey | String | Indicates the variant attributes key for the product, e.g., size or color. | Y |
| attributeValue | String | Indicates the variant attributes value for the product, e.g., Medium or Black. | Y |
| caseDetails[] - Indicates the item is packaged in multiple case levels Limit 3 – 1 per valid case type |
N | ||
| caseType | String | Valid Values for case types:case, pallet | Y |
| barCode | String | Barcode for the case | Y |
| height | Number | Height dimension for the case | Y (Dimensions are not required. If one dimension field is supplied, then all dimension fields in this group are required.) (The minimum value of the weight is 0.1) |
| length | Number | Length dimension for the case | |
| width | Number | Width dimension for the case | |
| weight | Number | Weight of the case | |
| numberOfUnits | Number | Number of units in the case | Y |
Response Attribute
| Parameter | Data type | Description |
|---|---|---|
| requestIdentifier | String | Request identifier. |
| transactionDate | String | Transaction date/time |
| success | Boolean | Status of the transaction. Valid Values:True or False. |
| items | ||
| itemId | String | FedEx item ID generated by the system. |
| sku | String | Item SKU. |
| 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-PDT-0001 | Product <item_sku> Required fields missing |
| ERR-PDT-0002 | Product <item_sku> already exist in the platform |
| ERR-PDT-0003 | Product <item_sku> battery type is needed when Contains Battery equals yes |
| ERR-PDT-0004 | Product <item_sku> Shelf Life Days is needed when Perishible equals yes |
| ERR-PDT-0005 | Product <item_sku> Attribute Type Value is needed |
| ERR-PDT-0006 | Product <item_sku> Attribute Value Type is needed |
| ERR-PDT-0007 | Product <item_sku> Invalid Case Type |
| ERR-PDT-0008 | Product <item_sku> Case Number Of Units is needed |
| ERR-PDT-0009 | Product <item_sku> Pallet Number Of Units is needed |
| ERR-PDT-0010 | Product <item_sku> Category value is not a match to the values available |
| ERR-PDT-0011 | Product <item_sku> Low Stock Threshold value does not match the values available |
| ERR-PDT-0012 | Product <item_sku> Type of Battery does not match the values available |
| ERR-PDT-0013 | Product <item_sku> Country of Origin value does not match the values available |
| ERR-PDT-0014 | Product <item_sku> Invalid <case_type> Number Of Units |
| ERR-PDT-0015 | Product <item_sku> Number Of Units cannot be updated when inventory is available. |
| ERR-PDT-0016 | Product <item_sku> Return Condition Disposition code does not match the values available |
| ERR-PDT-0017 | Product <item_sku> second quality SKU is missing |
| ERR-PDT-0018 | Product <item_sku> second quality SKU does not exist |
| ERR-PDT-0019 | Product <item_sku> Return Disposition Return to Vendor location is needed |
| ERR-PDT-0020 | Product <item_sku> Return to Vendor location does not match the values available |
| ERR-PDT-0021 | Product <item_sku> Field exceeds character limit |
| ERR-PDT-0026 | Product <item_sku> Country of origin is needed when International Shipping equals yes |
| ERR-PDT-0027 | Product <item_sku> HS code is needed when International Shipping equals yes |
| ERR-PDT-0028 | Product <item_sku> HS code is not in the required format |
| ERR-PDT-0029 | Connection is inactive |
| ERR-PDT-0030 | Required fields missing for bundles |
| ERR-PDT-0031 | Invalid product category code |
| ERR-PDT-0032 | Item quantity in the bundle is less than 2 |
| ERR-PDT-0033 | Invalid product selected |
| ERR-PDT-0034 | Product <item_sku> Shelf life days is not integer |
| ERR-PDT-0035 | Product <item_sku> Length is not greater than 0 |
| ERR-PDT-0036 | Product <item_sku> Width is not greater than 0 |
| ERR-PDT-0037 | Product <item_sku> Height is not greater than 0 |
| ERR-PDT-0038 | Product <item_sku> Weight is not greater than 0 |
| ERR-PDT-0039 | Product <item_sku> Invalid <case_type> Length |
| ERR-PDT-0040 | Product <item_sku> Invalid <case_type> Width |
| ERR-PDT-0041 | Product <item_sku> Invalid <case_type> Height |
| ERR-PDT-0042 | Product <item_sku> Invalid <case_type> Weight |
Country Codes
| Code | Name |
|---|---|
| US | United States of America |
| CA | Canada |
| AD | Andorra |
| AE | United Arab Emirates |
| AF | Afghanistan |
| AG | Antigua and Barbuda |
| AI | Anguilla |
| AM | Armenia |
| AO | Angola |
| AQ | Antarctica |
| AR | Argentina |
| AS | American Samoa |
| AT | Austria |
| AU | Australia |
| AW | Aruba |
| AX | Åland Islands |
| AZ | Azerbaijan |
| BA | Bosnia and Herzegovina |
| BB | Barbados |
| BD | Bangladesh |
| BE | Belgium |
| BF | Burkina Faso |
| BG | Bulgaria |
| BH | Bahrain |
| BI | Burundi |
| BJ | Benin |
| BL | Saint Barthélemy |
| BM | Bermuda |
| BN | Brunei Darussalam |
| BO | Bolivia (Plurinational State of) |
| BQ | Bonaire, Sint Eustatius and Saba |
| BR | Brazil |
| BS | Bahamas |
| BT | Bhutan |
| BV | Bouvet Island |
| BW | Botswana |
| BY | Belarus |
| BZ | Belize |
| CC | Cocos (Keeling) Islands |
| CD | Congo (the Democratic Republic of the) |
| CF | Central African Republic |
| CG | Congo |
| CH | Switzerland |
| CI | Côte d'Ivoire |
| CK | Cook Islands |
| CL | Chile |
| CM | Cameroon |
| CN | China |
| CO | Colombia |
| CR | Costa Rica |
| CU | Cuba |
| CV | Cabo Verde |
| CW | Curaçao |
| CX | Christmas Island |
| CY | Cyprus |
| CZ | Czechia |
| DE | Germany |
| DJ | Djibouti |
| DK | Denmark |
| DM | Dominica |
| DO | Dominican Republic |
| DZ | Algeria |
| EC | Ecuador |
| EE | Estonia |
| EG | Egypt |
| EH | Western Sahara |
| ER | Eritrea |
| ES | Spain |
| ET | Ethiopia |
| FI | Finland |
| FJ | Fiji |
| FK | Falkland Islands [Malvinas] |
| FM | Micronesia (Federated States of) |
| FO | Faroe Islands |
| FR | France |
| GA | Gabon |
| GB | United Kingdom of Great Britain and Northern Ireland |
| GD | Grenada |
| GE | Georgia |
| GF | French Guiana |
| GG | Guernsey |
| GH | Ghana |
| GI | Gibraltar |
| GL | Greenland |
| GM | Gambia |
| GN | Guinea |
| GP | Guadeloupe |
| GQ | Equatorial Guinea |
| GR | Greece |
| GS | South Georgia and the South Sandwich Islands |
| GT | Guatemala |
| GU | Guam |
| GW | Guinea-Bissau |
| GY | Guyana |
| HK | Hong Kong |
| HM | Heard Island and McDonald Islands |
| HN | Honduras |
| HR | Croatia |
| HT | Haiti |
| HU | Hungary |
| ID | Indonesia |
| IE | Ireland |
| IL | Israel |
| IM | Isle of Man |
| IN | India |
| IO | British Indian Ocean Territory |
| IQ | Iraq |
| IR | Iran (Islamic Republic of) |
| IS | Iceland |
| IT | Italy |
| JE | Jersey |
| JM | Jamaica |
| JO | Jordan |
| JP | Japan |
| KE | Kenya |
| KG | Kyrgyzstan |
| KH | Cambodia |
| KI | Kiribati |
| KM | Comoros |
| KN | Saint Kitts and Nevis |
| KP | Korea (the Democratic People's Republic of) |
| KR | Korea (the Republic of) |
| KW | Kuwait |
| KY | Cayman Islands |
| KZ | Kazakhstan |
| LA | Lao People's Democratic Republic |
| LB | Lebanon |
| LC | Saint Lucia |
| LI | Liechtenstein |
| LK | Sri Lanka |
| LR | Liberia |
| LS | Lesotho |
| LT | Lithuania |
| LU | Luxembourg |
| LV | Latvia |
| LY | Libya |
| MA | Morocco |
| MC | Monaco |
| MD | Moldova (the Republic of) |
| ME | Montenegro |
| MF | Saint Martin (French part) |
| MG | Madagascar |
| MH | Marshall Islands |
| MK | Macedonia (the former Yugoslav Republic of) |
| ML | Mali |
| MM | Myanmar |
| MN | Mongolia |
| MO | Macao |
| MP | Northern Mariana Islands |
| MQ | Martinique |
| MR | Mauritania |
| MS | Montserrat |
| MT | Malta |
| MU | Mauritius |
| MV | Maldives |
| MW | Malawi |
| MX | Mexico |
| MY | Malaysia |
| MZ | Mozambique |
| NA | Namibia |
| NC | New Caledonia |
| NE | Niger |
| NF | Norfolk Island |
| NG | Nigeria |
| NI | Nicaragua |
| NL | Netherlands |
| NO | Norway |
| NP | Nepal |
| NR | Nauru |
| NU | Niue |
| NZ | New Zealand |
| OM | Oman |
| PA | Panama |
| PE | Peru |
| PF | French Polynesia |
| PG | Papua New Guinea |
| PH | Philippines |
| PK | Pakistan |
| PL | Poland |
| PM | Saint Pierre and Miquelon |
| PN | Pitcairn |
| PR | Puerto Rico |
| PS | Palestine, State of |
| PT | Portugal |
| PW | Palau |
| PY | Paraguay |
| QA | Qatar |
| RE | Réunion |
| RO | Romania |
| RS | Serbia |
| RU | Russian Federation |
| RW | Rwanda |
| SA | Saudi Arabia |
| SB | Solomon Islands |
| SC | Seychelles |
| SD | Sudan |
| SE | Sweden |
| SG | Singapore |
| SH | Saint Helena, Ascension and Tristan da Cunha |
| SI | Slovenia |
| SJ | Svalbard and Jan Mayen |
| SK | Slovakia |
| SL | Sierra Leone |
| SM | San Marino |
| SN | Senegal |
| SO | Somalia |
| SR | Suriname |
| SS | South Sudan |
| ST | Sao Tome and Principe |
| SV | El Salvador |
| SX | Sint Maarten (Dutch part) |
| SY | Syrian Arab Republic |
| SZ | Swaziland |
| TC | Turks and Caicos Islands |
| TD | Chad |
| TF | French Southern Territories |
| TG | Turks and Caicos Islands |
| TH | Thailand |
| TJ | Tajikistan |
| TK | Tokelau |
| TL | Timor-Leste |
| TM | Turkmenistan |
| TN | Tunisia |
| TO | Tonga |
| TR | Turkey |
| TT | Trinidad and Tobago |
| TV | Tuvalu |
| TW | Taiwan (Province of China) |
| TZ | Tanzania, United Republic of |
| UA | Ukraine |
| UG | Uganda |
| UM | United States Minor Outlying Islands |
| UY | Uruguay |
| UZ | Uzbekistan |
| VA | Holy See |
| VC | Saint Vincent and the Grenadines |
| VE | Venezuela (Bolivarian Republic of) |
| VG | Virgin Islands (British) |
| VI | Virgin Islands (U.S.) |
| VN | Viet Nam |
| VU | Vanuatu |
| WF | Wallis and Futuna |
| WS | Samoa |
| YE | Yemen |
| YT | Mayotte |
| ZA | South Africa |
| ZM | Zambia |
| ZW | Zimbabwe |
Inbound Classification Codes
| Code | Name | Description |
|---|---|---|
| RET | RETURNABLE | A default classification used on most product that does not need separate segregation at the return center. |
| DES | DESTROY | A classification used on product that will be disposed of at the center. |
| RCL | RECALL | Depicts items being recalled for collection. |
| SAL | SALVAGE | Depicts items being sold on a secondary market. |
| CHA | CHARITY | Depicts items that are being donated. |
| REC | RECYCLE | Depicts items destined for recycling. |
| REF | REFURBISH | Depicts items that are to be sent for refurbishing. |
| RTS | RETURN TO STOCK | Depicts items going back to stock for fulfillment to a distribution or fulfillment center. |