Available APIs

Authentication - OAuth2.0

Orders

Inventory

Items

Inbound Shipments

Rmas

Labels

Receipt

Location

Tracking

Document

Webhook

Appointment

Troubleshooting

Create RMA

Creates a new RMA and all of the item level details required for a return. The RMA API has a flag within to depict if a label is needed or not.

Swagger

         
swagger: '2.0'
info:
  x-ibm-name: rmas
  title: Rmas
  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_Id: []
    Client_Secret: []
    oauth2:
      - Fulfillment_Returns
x-ibm-configuration:
  testable: true
  enforced: true
  phase: realized
paths:
  /rmas:
    post:
      responses:
        200:
          description: 200 OK
      parameters:
      - name: create_createrma_json_body
        required: true
        in: body
        schema:
          type: json
        description: ''
      - name: AccessToken
        type: string
        required: false
        in: header
        description: Enter Access Token, it is required header
      	summary: Create RMA
        description: Creates a new RMA and all of the item level details required for a return.  
		The RMA API does have a flag within to depict if a label is needed or not.

Sample Request

         
{
	"requestIdentifier" : "234234234234234",
	"rmaNumber" : null,
	"affiliatedMerchant": "Merchant",
	"customer" : {
		"firstName" : "John",
		"lastName" : "Smith",
		"addressLine1" : "1020 Orchard St",
		"addressLine2" : "",
		"city" : "Sacramento",
		"stateCode" : "CA",
		"zipCode" : "95814",
		"countryCode" : "US",
		"phoneNumber" : "888-787-8888",
		"emailAddress" : "test85@gmail.com"
	},
	"trackingNumber" : null,
	"shippingService" : null,
	"shippingCost" : null,
	"labelRequired" : null,
	"emailNotification" : null,
	"returnEmployeeId" : null,
	"returnEmployeeName" : null,
	"shipToAddressId" : null,
	"shippingCostResponsibility" : null,
	"externalASNId" : null,
	"casAccountNumber" : null,
	"billToFirstName" : null,
	"billToLastName" : null,
	"billToAddress1" : null,
	"billToAddress2" : null,
	"billToCity" : null,
	"billToStateCode" : null,
	"billToZipCode" : null,
	"specialtyFlag" : null,
	"orders" : [{
			"orderNumber" : "RMS-1451-O2",
			"orderDate" : "2017-02-15",
			"items" : [{
					"sku" : "testsku23",
					"quantity" : 3,
					"returnItemInfo" : {
						"returnReason" : "Wrong Size",
						"returnEligibilityOverride" : "true",
						"finalSale" : null
					}
				}
			]
		}
	]
}

Sample Response

Success Response

         
{
  "requestIdentifier": "234234234234234",
  "success": true,
  "rmas": [
    {
      "rmaId": "2408-1984",
      "rmaNumber": "2400",
      "shippingService": "FDXE",
      "shippingCost": 20.83,
      "shipToAddressId": "123098",
      "shipToAddressName": "CAD Location Name Update",
      "label": {
        "id": 15050,
        "labelURL": "http://<.........>/api/v1/labels/15050",
        "trackingNumber": "14147333522777"
      }
    }
  ]
}

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 Attributes

Parameter Data type Description Required
rmaNumber String If the retailer is set up to provide the RMA number from their host system, it will be sent here.
If the RMA number is assigned by the RMS system, this field is left blank.		 N
affiliatedMerchant String Specify the affiliated merchant the RMA is being created for. This field must match the affiliated
merchant field configured in the Retailers Configuration screen.		 N
shippingService String If you are using a label service outside of FedEx Fulfillment to produce the shipping label the service type would be sent here.
Valid Values: See list below in RMA Shipping Service Codes 		N
trackingNumber String If you are using a label service outside of FedEx Fulfillment to produce the shipping label, the tracking number would be sent in this field. N
shippingCost String If you are using a label service outside of FedEx Fulfillment to produce the shipping label, the net cost of the shipment would be sent in this field. N
labelRequired String If you would like the commerce platform to generate a shipping label, mark this field as true. The label will be stored in the system and the URL will be sent back in the response to this request.
Valid Values: true or false.		 N
emailNotification String Indicates whether an email of the label with a QR Code of the RMA number is sent to the consumer requesting the return.
Valid Values: true or false.		 N
externalASNId String If an advance shipping notification (ASN) record was created by the host system of the merchant, the ID can be passed to be used a link to the receiving party. N
shipToAddressId String A merchant can choose a specific location where an item will be returned directly. If you specify a location, proximity by miles will be ignored.
If Null the system will use the proximity by miles function to select the appropriate return address.
Valid Data: All eligible address IDs must be listed in FedEx Fulfillment.		 N
shippingCostResponsibility String If the merchant's system decides who is responsible for the cost of the shipment, it will be depicted here.
Valid Data: Consumer, Retailer		 N
returnEmployeeName String First and last names of your representative who is permitted to return product on behalf of the company. N
returnEmployeeId String Employee ID of your representative who is permitted to return product on behalf of the company. N
casAccountNumber Number The Commercial Account Services (CAS) number sent to depict which account number to use during the receipt of this return. N
billToFirstName String The bill-to first name for this return. N
billToLastName String The bill-to last name for this return. N
billToAddressLine1 String The bill-to address 1 for this return. N
billToAddressLine2 String The bill-to address 2 for this return. N
billToCity String The bill-to city for this return. N
billToStateCode String The bill-to state code for this return. N
billToZipCode String The bill-to zip code for this return. N
specialtyFlag String Indicates do not credit, early credit, or gift return for this return. N
orders[]      
orderNumber String The original order number to which the item being returned belongs. This number will be stored in the RMA record being created to allow a reference back from the merchant's order management Ssstem. Y
orderDate String The original date when the order was placed in the merchant's order management system. Y
orders[].items[]      
sku String The SKU belonging to the item selected for return. This SKU matches the existed merchant data that's loaded into FedEx Fulfillment.
Item SKUs should be rolled up and a total expected quantity should be given.		 Y
quantity Number Total number of a specific SKUs being returned in this RMA. Y
orders[].items[].returnItemInfo      
returnReason String The reason the consumer is returning the item. Y
returnEligibilityOverride String Indicataes whether you would like to force an item SKU to be returned even if the system logic dictates it is not returnable. If this flag is set, it will override any processing logic limitations.
Valid Values: true or false.		 N
finalSale Boolean Indicates whether the item was in a final sale status when it was sold. N
customer      
firstName String First name of the consumer requesting the return. Y
lastName String Last name of the consumer requesting the return. Y
addressLine1 String First line of the address of the consumer requesting the return. Y
addressLine2 String Second line of the address of the consumer requesting the return. N
city String City of the consumer requesting the return. Y
stateCode String State of the consumer requesting the return. Y
zipCode String Zip code of the consumer requesting the return. Y
countryCode String Country of the consumer requesting the return. Y (If blank defaulted to US)
phoneNumber String Phone number of the consumer requesting the return. Y (If the retailer is Single Ship)
emailAddress String Email address of the consumer requesting the return. This email address will be used for any auto-notifications or sending of a label for the return. N

Response Attribute

Parameter Data type Description
requestIdentifier String Request identifier.
transactionDate Date Transaction date/time.
success boolean Status of the transaction
Valid Values: true or false
rmas[]    
rmaId String This ID is created when the RMA is committed into FedEx Fulfillment. It will be used on any subsequent calls made to the system in reference to this RMA.
Three other APIs use this ID: Location, Tracking and Cancel.
rmaNumber String The RMA number that was given by the merchant or created by FedEx Fulfillment and recorded for the return.
shippingService String The FedEx shipping service used to complete the return of the item.
Valid Values: FDXE, FDXG, FDSP, OTHER
shippingCost Number The final price to ship the return to the destination.
shipToAddressId String The address ID where the returned item will be shipped.
shipToAddressName String The address name where the returned item will be shipped.
rmas[].label    
id Number The unique identifier that depicts the row where the label is stored in the system. Will be passed in the label URL to obtain the label PDF.
labelURL String If a label was requested, the URL for the label PDF is listed here.
trackingNumber String The tracking number assigned to the label used for the return.
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-RMA-0000 System error message.
ERR-RMA-0003 Retailer return address is missing to process return.
ERR-RMA-0004 Retailer reqire RMA number.
ERR-RMA-0010 Exception in creating Receipts.
ERR-RMA-0011 This RMA Number is already in use. Please enter a unique RMA Number..
ERR-RMA-0012 No Rma found for the given id : {id}.
ERR-RMA-0013 Exception in calling RMA oneup Service.
ERR-RMA-0014 Exception in calling create action.
ERR-RMA-0015 New RMA not required. No rma receipts found for rma Id: {id}.
ERR-RMA-0020 Retailer not found for the request.
ERR-RMA-0021 No Fedex Account is found for the given location to process return.
ERR-RMA-0024 Invalid affiliatedMerchant field: the value does not match the one defined in the Retailer screen.
ERR-RMA-0030 Item Details not found : {sku}.
ERR-RMA-0031 Item Sku : {sku} is Marked as non returnable.
ERR-RMA-0033 Item Sku : {sku} in Order: {order} can not be returned after {days} day(s) of Order.
ERR-RMA-0034 New RMA not required. All the Items are alredy received {id}.
ERR-RMA-0040 Error calling generate label service.
ERR-RMA-0050 Error in ASN Service.

RMA Shipping Service Codes

Code Name
FDXE FedEx 2Day®
F2DA FedEx 2Day® A.M.
FDXG FedEx Ground®
FDSP FedEx SmartPost®
FPON FedEx Priority Overnight®
FSON FedEx Standard Overnight®
FEXS FedEx Express Saver®
OTHER Other Shipping Service