The shipping method UPS (OAuth) in Xentral allows for flexible and reliable shipment of your goods. This article explains how to set up the shipping method UPS (OAuth) in Xentral.
You will find step-by-step instructions how to set up the integration, select the correct service and package codes, create custom documents automatically and communicate tracking information back to your online store. This way, you keep track of your shipments and ensure that your customers receive their orders on time.
The shipping UPS (OAuth) is especially relevant for you if you deliver to international customers, need to delivery your products very quickly or if you sell high-priced goods that need particularly fast and reliable delivery.
The Xentral shipping method UPS (OAuth) offers you the following features:
-
National and international shipping
-
Feedback of the tracking number to your online shops and sales platforms
-
Automatic shipping label printing directly in Xentral
-
Entering the product type for international shipments (e.g. Standard, Express, Saver)
-
Support for parcel, express and bulky goods shipments
-
Automatic creation and transfer of customs information for non-EU shipments
-
Access to additional services such as cash on delivery, Saturday delivery, transport insurance, signature services
To use UPS (OAuth) as a shipping method in Xentral, you first create a new shipping method. Then, you activate it with your existing contract data from UPS. It only takes a few minutes and a few steps to be able to ship your first products with UPS!
Important
Before you start setting up the shipping method in Xentral, make sure that the OAuth authentication is activated in your UPS account. To do so, follow the instructions on the UPS developer page. Then, log into the UPS developer portal and activate OAuth for your account.
Proceed as follows to set up the shipping method UPS (OAuth) in Xentral.
-
Use the Smart Search to search for Shipping methods,
-
Click on + NEW in the upper right corner.
-
Click on UPS (OAuth).
-
Carry out the settings as described in the table below.
-
Click on Save.
|
Setting |
Explanation |
|---|---|
|
Designation |
Enter a name for the shipping method that will later be displayed in Xentral during order processing. The designation is only visible to you and your employees. Make sure that each designation exists only once in Xentral so that the shipping method can always be uniquely identified. |
|
Type |
This is an internal field label that is required for mapping to your online stores and other sales platforms. ImportantDo not change this type! |
|
Module |
Select the correct module from the drop-down menu. The module name must be identical to the name of the shipping method that you are currently setting up. |
|
Project |
Optional: Assign a project. This assignment is required if you want to limit the shipping method to a specific sales channel or project (for example, a specific branch office). |
|
Active |
Activate this option after you have carried all the necessary settings for the shipping method. NoteYou can deactivate shipping methods that are no longer in use later. Note, however, that deactivated shipping methods will only be displayed in receipts that have already been created. In newly created receipts and in user interfaces such as the sales order overview or in the customer data, a deactivated shipping method is no longer available for selection. You can also delete shipping methods. However, this will also delete the shipping history. Therefore, you should only delete incorrectly created shipping methods that you have not used productively. |
|
No postage check |
You can use this option to deactivate the postage check in the sales order. If the postage check remains active, a red sales order traffic light icon will be displayed in case no postage item is included in the sales order. This prevents the postage item from being forgotten during manual order creation. Consider whether you want to activate or deactivate this option based on your own workflows and how you work with Xentral. If you typically create a high number of sales orders manually in Xentral, it may be useful not to activate this option, so that the postage is always reliably included in the sales order, especially for high-priced products or international shipments. |
|
Printer shipping label |
Select the printer you want to use by default for the shipping labels from the drop-down menu. Note that only printers that you have already set up in Xentral can be selected here. Depending on how and where the shipping process is handled in your company, you can choose exactly the printer you need here - whether directly at your desk or at the packing table in the warehouse. |
|
Printer export |
Only relevant for international shipping: From the drop-down menu, select the printer that should be used for customs documents (CN23) by default. |
|
Shipping email to buyer |
Determine rules regarding the way shipping notifications should be sent to your customers by email as soon as the shipment is on its way. The following three options are available: Default behavior: The existing logistics settings from the project are used. You can carry out these settings in the Settings > Basic Settings > Projects > Open Project > Tab: Settings > Tab: Logistics / Shipping menu. In the Stage 1 (Picking/Order picking) and Stage 2 (Pack) sections, you can activate the check boxes named Email to inform your customers about the status of order processing. No shipping mail: No shipping information will be sent by email for this shipping method. Custom text template: For this shipping method, the selected text template will be sent via email. You need to create this template in advance in the Settings > Basic Settings > Receipts > Text templates menu. Then select the desired template from the Text template drop-down menu. This selection will not use the project’s logistics settings for this shipping method. |
|
Deliveries supported |
When setting up the shipping method, this option is activated by default. Once you have carried out all the other necessary settings and set the shipping method to Active, you can select the shipping method in sales orders, delivery notes and in the dispatch center. |
|
Returns supported |
Activate this option to allow your customers to send returns for sales orders originally created using this shipping method. |
|
UPS OAuth connection |
Click on Connect next to this option. You are forwarded to your UPS account. Log in and follow the instructions. You are then automatically redirected to Xentral afterwards. Next to the setting OAuth connection, the word Info is now displayed instead of Connect. |
|
Preferred return shipping method |
Select a preferred shipping method for returns. If you create a return for a sales order in Xentral with the present shipping method, the shipping method selected here is automatically preselected in the return order. This setting is only relevant in cases of manual return creation. |
|
Sender name / contact person / street / house number / ZIP code / place / state / country / email / phone /internet / tax ID |
Enter your company name in the Sender name field and enter your company's address details in the remaining fields. The tax ID is your company’s VAT ID. You can enter the email address of your customer service team in the Internet field. The information you provide here will appear as the sender address on your shipping labels. NoteThe country needs to be entered as 2-digit ISO code, meaning DE for Germany in case the sender country is Germany. |
|
Default weight |
Optional: What is the typical weight of the shipments you send with this shipping method? Enter a default weight in kg here. This weight is transmitted to the shipping service provider each time a shipping label is created, unless it is manually changed in Xentral before the shipping label is printed. |
|
Adjust weight in |
To create the shipping label, an accurate calculation of the total weight of the shipment including packaging material is required. Xentral automatically calculates the shipment weight in the background by adding up the total weight of the items included in the sales order. The present option adds a weight specified by you. This creates a total value for the shipping registration, which is taken into account when creating the shipping label and automatically reported to the shipping service provider. Decide whether the additional weight of the packaging material should be expressed in kg or %. Use the following setting called Adjust weight to define the extra weight more precisely. |
|
Adjust weight to |
This setting allows you to specify your details for the Adjust weight in setting. Enter the additional weight of the shipment in kilograms or percentages here, depending on the previous selection. Which calculation method and which specific values you choose depends on the packaging type of your products and the packaging materials you use. |
|
Length / Width / Height |
Enter the default dimensions of your shipments in cm. These measurements are then transmitted to the shipping service provider in case they are not adjusted manually before printing the shipping label in Xentral. |
|
Standard Service Code |
Enter the Standard Service Code from the UPS customer portal. One Standard Service Code always represents one UPS product that you have booked. If, for example, you have booked the products for both standard and express delivery with UPS, you create a separate shipping method for each product in Xentral. The following list contains the most frequently used Standard Service Codes:
|
|
Standard Service Description |
Enter the Standard Service Description from the UPS customer portal, e.g. UPS Standard. |
|
Standard Package Code |
Enter the Standard Package Code from the UPS customer portal. The code 02 is suitable for the majority of use cases, since it means that you hand over your shipments to UPS in your own packaging. In case your contract includes packaging material to be provided by UPS, you can find the required Standard Package Code in the GLS customer portal. |
|
Standard Package Description |
Optional: You can freely assign a Standard Package Description, such as Customer Supplied. |
|
Reference 1 on label |
Use the variables that are displayed to determine whether you want to print additional information on the UPS shipping label. You can also enter a free text. The following variables are available: {DELIVERY_NOTE}, {ORDER}, {PROJECT}, {YOUR_ORDER_ID}, {INTERNET}. ImportantYou can only use one of the variables! |
|
Reference 2 on label |
Use the variables that are displayed to determine whether you want to print additional information on the UPS shipping label. You can also enter a free text. Use this option if a single reference (Setting Reference 1 on label) is not sufficient for your business needs. The following variables are available: {DELIVERY_NOTE}, {ORDER}, {PROJECT}, {YOUR_ORDER_ID}, {INTERNET}. ImportantYou can only use one of the variables! |
|
Volume weight |
Activate this option so that Xentral can automatically calculate the volume weight from the shipment dimensions and transfer this information to the shipping service provider automatically during shipment registration. |
|
Deactivate address validation |
Activate this option to disable the address validation that is carried out by UPS. |
|
Export reason |
Only relevant for international shipping: Enter the export reason here. These are the possible options:
|
|
Logging |
Activate this option to log the data exchange with the shipping service provider in an additional XML file. The file will then be saved locally in the directory userdata/tmp. |
|
Save tracking number to sales order |
Activate this option to save the tracking number in Xentral directly to the corresponding sales order after the shipping label has been created. This means that the tracking number is permanently saved in your system and you do not have to rescan the shipping label after creation to record this data in Xentral. |
|
ZPL as output format |
Activate this option to request the shipping label in the format ZPL instead of as a PDF file. ZPL (Zebra Programming Language) is a specific file format for Zebra label printers. NoteBy default, ZPL files contain no file ending and cannot be opened manually, since they are intended for immediate processing by the label printer. If you want to check the content of a ZPL file, you can use a so-called ZPL viewer (available online) to do so. |
|
UPS Sandbox (test mode) |
Activate this option to test shipping label printing in the UPS Sandbox before using the shipping method productively. Each shipping label created in sandbox mode is marked as a SAMPLE by a dedicated imprint to show that it will not be billed. |
|
UPS Quantum View Notify |
Activate this option to have delivery notifications sent to your customers automatically by UPS. This way, your customers are directly notified by UPS regarding delivery of the shipment. |
|
Paperless Invoice |
|
|
Exclude JIT components on CN22 form |
Only relevant for international shipping: Activate this option to exclude the individual components of just-in-time bills of material from the CN22 form in case products of this nature are included in the shipment. If this option is activated, only the main or head product of the bill of materials is listed. ImportantWhen shipping just-in-time bills of material, always make sure that all required and relevant data for customs processing (customs tariff number, country of origin, weight) are correctly maintained in the product master data of this main product. Otherwise, errors will occur during creation of the shipping label. Make sure that all the information outlined above is complete, no matter if you activate or deactivate the present option. Customs tariffs number, country of origin and weight are maintained in the respective fields in the Sell > Products > Open product > Tab: Details > Section: Manufacturer menu. More information on just-in-time bills of materials is available in the article Bill of materials. |
|
Auto-fallback for HS code |
Only relevant for international shipping: In case items without customs tariff number in the respective product master data in Xentral are included in the shipment, creating a shipping label will not be possible. You can avoid this error by entering a customs tariff number here. This number will then be used in case no customs tariff number is saved in the product master data. ImportantWe generally recommend that you carefully maintain all product master data so that errors are avoided from the start. The customs tariff number is maintained under Sell > Products > Open product > Tab: Details > Section: Manufacturer menu. |
|
Bill third party for duties and taxes |
Activate this option in case the shipping costs are not to be billed to you as the sender, but to a third person or company instead. In case you are using the UPS billing model Freight Collect (Recipient pays shipping costs) and Third Party, you need to activate this option. |
|
Third party account number |
In case you are using the UPS billing model Third Party, enter the UPS customer number of the third party who is paying for shipping here. UPS will then bill the shipping costs to them. |
|
Third party postal code / country |
In case you are using the UPS billing model Third Party, enter the ZIP code and country of the third party who is paying for shipping here. |
Once you have carried out all the settings as described above, you can test the shipping label printing in the dispatch center or in an individual delivery note. To do so, proceed as follows.
-
Click on the pencil icon on the right to open a delivery note in the Delivery note module.
-
Open the Details tab.
-
Scroll down until you reach the Delivery note section.
-
Select the shipping method UPS (OAuth) from the Shipping method drop-down menu.
-
Click on Save.
-
Open the Shipping label tab.
-
Adjust the address details, if required.
Important
In case of international shipping, it is mandatory to fill in the fields Name, Name 3 (c/o) and Phone.
-
Click on Print shipping label.
-
Download the shipping label. Now, you can open it and check for any errors.
After your test print is complete, you can cancel the parcel label in the UPS Business Customer Portal.
Note
Note that you can only cancel UPS shipping labels as long as UPS has not picked up the respective parcel at your premises. Shipping labels that have not been used can be cancelled within a 90-day period.
The following error messages may occur when using the shipping method UPS (OAuth):
|
Error message |
Explanation and solution |
|---|---|
|
The request is not well formed |
Some of the data in the shipping method contain at least one special character (e.g. & or *). Please check if your user name, password or other data contain special characters and remove those. |
|
Missing or invalid ShipTo PhoneNumber Code: 120209 |
This error message occurs when there are problems with the phone number. There are two possible reasons for this:
|
|
Failed to refresh oauth token |
The authentication has been rejected by UPS. You can fix this issue by renewing your authentication as follows: |
|
Missing or invalid ship to attention name (ErrorCode:120201) |
This error occurs when the recipient’s name field in the delivery address is either empty, contains invalid characters or if the maximum number of 35 characters has been exceeded. Check the input for the recipient’s name and fix it, if necessary. |
|
Missing or invalid ship to address line 1 (ErrorCode:120202) |
This error message indicates that UPS cannot interpret address line 1 of the recipient’s address. This means that the field Street/House number is either empty or contains invalid characters. Check the input in the field Street/House number and fix it, if necessary. |