OmniReturns Label Creation API

POST /labels/printshipment

Purpose

This interface allows you to create a return label via OmniReturns

Authentication

All HTTP requests will require token key. The key needs to be declared as the HTTP Request Header.

The access key will be provided by Seko on request.

Parameters

Request Parameters

Parameter	Mandatory	Type	Description

Parameter	Mandatory	Type	Description
Destination	Y	Refer to Receiver Information Refer to Address Information This is the first mile destination of the return. If returns are being processed by Seko, this will be our hub address which needs to be requested from your account manager
SendTrackingEmail	Optional	Boolean	Should a track and trace email be sent on pickup. Use “false” if you send your own email to the customer with the label
Origin	Y	Same attributes as Destination.
Packages	Y	Refer to Package Information
Commodities	Y	Refer to Commodity Information
DeliveryReference	Y	String (1000 characters)	Shipment reference number / Order Number / RT Number
Reference2	Optional	String (500 characters)	Additional Shipment Reference / OrderNo field.
Reference3	Optional	String (500 characters)	Additional Shipment Reference
RPSProcessing	Mandatory if returns are processed at a Seko Hub	Boolean	If this return will be processed at a Seko hub, use “true” If this return will going direct to the retailers or a 3rd party facility, use “False” or omit
Outputs	Optional	JSON string array. Refer to Output Information
Carrier	Optional	String(50 Characters)	Where multiple carrier options are available, a carrier can be pre-nominated. E.g “Omni Parcel”
Service	Optional	String	Where multiple service options are available, a service can be pre- nominated. Eg. “Air Tracked” or “Air Untracked”
Postcodevalidate	Optional	Boolean	If “true” OmniParcel will check postcode and overwrite destination suburb and city provided in API request. Available for New Zealand only.
ShipType	Y	String	MUST be“INBOUND” for returns
ProductCategory	Optional	String (50 characters)	Product category used to group products
SendLabel	Optional	String (1 Character)	“Y” Or “N” – if “Y” then email from OmniParcel will be sent to the customer containing the return label
IncludeLineDetails	Optional	Boolean	If ``True`` then in Response Item details will be provided with TrackingBarcode details.

Receiver Information

Parameter	Mandatory	Type	Description

Parameter	Mandatory	Type	Description
Name	Y	String (50 characters)	Consignee name/Business name
Email	Y	String(200 characters)	Email address
ContactPerson	Y	String(50 characters)	Contact person for delivery
PhoneNumber	Y	String(50 characters)	Phone contact number for delivery

Address Information

Parameter	Mandatory	Type	Description

Parameter	Mandatory	Type	Description
BuildingName	Y	String (50 characters)	Address identifier, e.g. Unit 1, Level 2
StreetAddress	Y	String (50 characters)	Street address e.g. 32 Sommer Place
Suburb	Y	String (50 characters)	Suburb Name
City	Y	String (50 characters)	City/State Name. AU/US – States to be provided as abbreviations, eg. VIC – Victoria CA – California
PostCode	Y	String (20 characters)	Postal code or Zip code
CountryCode	Y	String (2 characters)	2 letter Country code, e.g. US, NZ, AU, CN, CA, etc (Please use GB instead of UK)

Package Information

Parameter	Mandatory	Type	Description

Parameter	Mandatory	Type	Description
Name	Y	String (50 characters)	Consignee name/Business name
ID	N	String	Number to identify package
Length	Y	Decimal (4dp)	Length of package in centimeters. Use 1 if not available
Width	Y	Decimal (4dp)	Width of package in centimeters. Use 1 if not available
Height	Y	Decimal (4dp)	Height of package in centimeters. Use 1 if not available
Kg	Y	Decimal (4dp)	Weight of package in Kilos
Type	Y	String (30 characters)	Package type, Valid values are: Bag, Box, Carton, Satchel Use Box if unsure

Commodities Parameters

Parameter	Mandatory	Type	Description	Example

Parameter	Mandatory	Type	Description	Example
Description	Y	String	Product name or description of the item	Leave With Me Dress In Navy Fl
Units	N	Numerical	Count of specific item	1
UnitValue	Y	Decimal	Value of the item per unit	25
UnitKg	Y	Decimal	Weight of the item per unit	0.25
Country	N	String	Country of items origin	New Zealand
Currency	Y	String	Currency of UnitValue	NZD
ItemNo	N	String	Item Number	12312
SKU	Y	String	SKU Number	ST1306B-white
Reason	Y - if Seko is processing	String	Reason this item is being returned	Too Big
ReturnAction	Y - if Seko is processing	String	Reconciliation method supplied to the customer for the return	REFUND
CommodityCode	Y - if return will go internationally		HS Code used by customs to classify the product	430310

Output Information

Parameter	Mandatory	Type	Description

Parameter	Mandatory	Type	Description
LABEL_PDF	Optional	String(200)	Label is presented on an A4 page
LABEL_PNG_100X175	Optional	String(200)	Label is presented as a PNG image with dimension 100mm x 175mm
LABEL_PNG_100X150	Optional	String(200)	Label is presented as a PNG image with dimension 100mm x 150mm
LABEL_PDF_100X175	Optional	String(200)	Label is presented as a PDF with dimension 100mm x 175mm
LABEL_PDF_100X150	Optional	String(200)	Label is presented as a PDF with dimension 100mm x 150mm

Consignment Response Parameters

If a label is provided by the label at the time of consignment creation, this will be provided in the response. Hong Kong does not respond with the label and is not provided.

Parameter	Type	Description

Parameter	Type	Description
CarrierId	Decimal	Internal OmniParcel identification number for the carrier
CarrierName	String	Courier Name
Message	String	Notification message for shipment create request
Errors	String	Validation errors if fields are incomplete or incorrect.
SiteId	Decimal	Your account site Id
Consignments	String	Consignment and tracking numbers
IsFreightForward	Boolean	Not relevant for returns
TrackingUrl	String	OmniParcel tracking URL, this will only show first mile tracking events. Not the end to end tracking for a return (processing, consolidation)
Cost	Decimal ( 2dp)	Cost of label
CarrierType	Integer	Internal Carrier Type
IsSaturdayDelivery	Boolean	Not relevant for returns
IsRural	Boolean	Not relevant for returns
IsOvernight	Boolean	Not relevant for returns
HasTrackPaks	Boolean	Not relevant for returns

Error Response Parameters

Parameter	Type

Parameter	Type
Property	String
Message	String

API

Test: https://test.omniparcelreturns.com/api/labels/printshipment

Example

Headers

Access-Key:  [access_key_for_site_account]
Content-Type:  application/json;  charset=utf-8

Body

{
    "DeliveryReference":"OrderNumber123",
    "Reference2":"RMA1234",
    "Reference3":"",
    "RPSProcessing":"true",
    "Origin":{
        "Address":{
            "BuildingName":"",
            "StreetAddress":"Main Street",
            "Suburb":"GLENWOOD",
            "City":"New South Wales",
            "PostCode":"2768",
            "CountryCode":"AU"
             },
        "Name":"Destination Person",
        "ContactPerson":"Destination person",
        "PhoneNumber":"0411375332",
        "Email":"test@destinationcomp.com"
         }
    "Destination":{
        "Address":{
            "BuildingName":"",
            "StreetAddress":"Temp Street",
            "PostCode":"2190",
            "CountryCode":"AU",
            "Suburb":"Chullora",
            "City":"NSW"
            },
        "Id":1,
        "Name":"RETURNS – retailer name",
        "ContactPerson":" JOHN SMITH",
        "PhoneNumber":"1800 951 411",
        "Email":" destinationemail@test.com",
        "DeliveryInstructions":"",
        "CostCentreName":" mysite.com"
    },
    "Commodities":
    [
      {
        "Description":"Leave With Me Dress In Navy Fl", 
        "Units":"1",
        "UnitValue":"62.95",
        "UnitKg":"0.1",
        "Country":null, "Currency":"AUD",
        "ItemNo":"1212121",
        "SKU":"ST1306B-white",
        "Reason":"Too Big"
        "CommodityCode":"HS456"
      },
       {
        "Description":"All Shook Up Dress in Black", 
        "Units":"1",
        "UnitValue":"59.46",
        "UnitKg":"0.1",
        "Country":null, 
        "Currency":"AUD", 
        "ItemNo":"13131313", 
        "SKU":"W79361-white",
        "Reason":"Not as Pictured"
        "CommodityCode":"HS456"
      },
      {
        "Description":"Miss Independent dress in bla", 
        "Units":"1",
        "UnitValue":"42.45",
        "UnitKg":"0.1",
        "Country":null, 
        "Currency":"AUD",
        "ItemNo":"1231232",
        "SKU":"W79361-black",
        "Reason":"Not as Pictured"
        "CommodityCode":"HS456"
      },
      {
        "Description":"Leave With Me Dress In Navy Fl", 
        "Units":"1",
        "UnitValue":"62.95",
        "UnitKg":"0.1",
        "Country":null, "Currency":"AUD",
        "ItemNo":"1212121",
        "SKU":"ST1306B-white",
        "Reason":"Too Big",
        "ReturnAction":"Refund",
        "CommodityCode":"13fdaf"
     }
    ],
    "Packages":
    [
      {
        "Name":"Leave With Me Dress In Navy Fl", 
        "Id":"173646",
        "Height":"0.1",
        "Width":"0.1",
        "Kg":"0.1",
        "Length":"70",
        "Type":"Box", 
      }
    ],
      "issignaturerequired":false,
      "PrintToPrinter":false,
      "CarrierLogo":true,
      "Outputs":["LABEL_PDF"],
      "SendTrackingEmail":false,
      "ShipType":"INBOUND",
      "SendLabel":"Y",
      "Service":"",
      "Carrier":"",
}

Response

Success

{
    "CarrierId": 727,
    "CarrierName": "Australia Post eParcelV3 Returns",
    "IsFreightForward": true,
    "IsOvernight": false,
    "IsSaturdayDelivery": false,
    "IsRural": false,
    "HasTrackPaks": false,
    "Message": "Connote created and print queued.",
    "Errors": [],
    "SiteId": 1469833,
    "Consignments": [
    {
        "Connote": "ABC112200",
        "TrackingUrl": "http://track.omniparcel.com/1469833- ABC112200",
        "Cost": 15.94,
        "CarrierType": 1,
        "IsSaturdayDelivery": false,
        "IsRural": false,
        "IsOvernight": false,
        "HasTrackPaks": false,
        "ConsignmentId": 17766035,
        "OutputFiles": {
            "LABEL_PDF":
            ["JVBERi0xLjQKJdP0zOEKMSAwIG9iago8PAovQ3JlYXRpb25EYXRlKEQ6MjAxOTAyMjgxNzQ1NDUrMTEn MDAnKQovVGl0bGUoT21uaVBhcmNlbCBGcmVpZ2h0IExhYmVsKQovQXV0aG9yKE9tbmlQYXJjZWwuY2 9tKQovU3ViamVjdChMYWJlbCkKL0tleXdvcmRzKE9tbmlQYXJjZWwpCi9DcmVhdG9yKFBERnNoYXJwIDE uMzIuMzA1Ny1nIFwod3d3LnBkZ …"]
        },
        "Items": null
    }
    ],
    "DestinationPort": "SYD",
    "Downloads": [],
    "CarrierType": 1,
    "AlertPath": null,
    "Notifications": [],
    "InvoiceResponse": "No Invoice found",
    "LogoPath": "http://cdn.omniparcel.com/images/auspost_logo_h50.png"
}

Failure

Error Response

Error Response	Definition

Error Response	Definition
No applicable rate resolved.	Rates must be explicitly configured for each account, for both origin and destination. This error means the country you have requested a label for has not been configured. You will need to check with your Account Manager.
Request Timeout	The request took longer than 60 seconds to complete so was ended. This could be due to the carrier taking too long to respond. Please try again.
. . . Your combination of suburb, state & postcode doesn't match. . . .	These address fields are validated by the Omni systems and the carrier. If validation failed in either system, you will get a similar error message. You will need to check these details and resend the request with the correct data. You can use the local carriers website to find the correct details.
. . . The attempted Suburb\/City\/Postcode combination does not exist in the database . . .	per above
. . . OmniParcel character limit for field [fieldname] is 1 to 50 characters but carrier limit for this field is 35 characters . . .	You have sent a field which exceeds the character limit. You will need to edit this field and resend.

This is not an exhaustive list of error messages due to the significant carrier integrations we have. We have aimed to provide an informative error message however, if you receive an error message you are unsure how to resolve, please contact OmniSupport - OmniReturns.

Printing

If you would like the API request to send the label directly to your printer, you will need to have the OmniParcel Print Agent installed on the PC where the printer is located.

To download the OmniParcel Print Agent, click here.

Manifest

Return Consignments do not require to be manifested.

Tracking

Please refer to the Returns Webhook documentation to acquire tracking information about return Consignments.