↑↓ selectEnter openEsc close

    1. Elbuz
    2. Delivery services in Elbuz

    UPS API in Elbuz: waybill from an order, label, courier and tracking

    5 min readUpdated

    Elbuz works with the UPS API through your developer.ups.com application. The waybill, label and courier are done from the order card; statuses update every 10 minutes.

    When you need this:

    • You ship from Poland or another EU country — address and country come from the order, no UPS account needed.
    • A label needs reprinting — works days later too.
    • Pickup from your address — request a UPS courier from the waybill.
    • “Where's my parcel?” — the UPS status shows in the order and the parcel register.

    Where to start: create an application on developer.ups.com → enter the keys in Elbuz.

    What UPS does in Elbuz

    • Connection — Client ID, Client Secret, UPS account number and the UPS test environment.
    • Waybill from an order — recipient, address, weight and dimensions are filled in automatically.
    • Label — print and reprint by waybill number.
    • Courier pickup — pickup date and hours; UPS replies with a request number.
    • Parcel statuses — every 10 minutes; your code table drives order status changes.

    How to connect the UPS API: keys and account number

    Where to get the UPS Client ID and Client Secret

    1. Sign in to developer.ups.com with your UPS account and choose “Create an Application” (or “My Apps” → “Add Apps”).
    2. Select the UPS account number the application is linked to and accept the UPS API Access Agreement.
    3. Add the Shipping, Tracking and Pickup products; Authorization (OAuth) is added automatically.
    4. Save the application and copy the Client ID and Client Secret from “My Apps”.

    Your UPS account number is in the UPS profile, “Accounts and Payments” section. No account in Poland yet — open one on ups.com.

    The Community plan is free. Under UPS pricing, per month: tracking — 90,000 requests, waybills and courier — unlimited, label reprints — 10,000. Each print from Elbuz is one label reprint request.

    What to enter in Elbuz

    Where: External services and integrations → Delivery → “UPS”.

    FieldWhat to enter
    “Active”On — otherwise the UPS waybill won't open
    “User”Client ID
    “Password”Client Secret
    “UPS account number (Shipper Number)”the 6-character account number; UPS charges this account
    “Default service”The service for all waybills (which to choose)
    “Sandbox environment”Turn on for testing, turn off for real work
    “Sender” blockCompany, contact person, ISO country code (empty — PL), postcode, city, street, house, phone, email. This is the sender address on the waybill and the pickup address
    “Company”Your company, if each has its own UPS account; a company record takes priority over the general one
    UPS connection form: API credentials, UPS parameters and sender block
    1User and Password
    2UPS account number (Shipper Number)
    3Default service
    4Sandbox environment
    5Sender
    1. User and Password — the Client ID and Client Secret of the app from developer.ups.com.
    2. UPS account number (Shipper Number) — your UPS customer account number.
    3. Default service — the UPS service that is pre-selected on a new waybill.
    4. Sandbox environment — switch that sends requests to the UPS test environment instead of live.
    5. Sender — the pickup address and the return address printed on the label.

    The form saves itself as soon as you change a field. After saving, “Password” shows dots, and an empty field doesn't erase the key.

    Elbuz doesn't check the keys when you save. The first waybill shows a key error: “UPS OAuth: ‹UPS text›”.

    Which service to choose

    ServiceWhat it is
    UPS Standard (11)Default
    UPS Express Saver (65)Express; in other EU countries UPS calls it UPS Worldwide Saver
    UPS Express (07)Express
    UPS Expedited (08)International service

    Names and codes are from the UPS service reference; which ones you can use depends on your UPS contract. There is one service for all waybills; you can't change it in the waybill form.

    UPS test environment

    Turn on “Sandbox environment” — waybills go to the UPS test environment (CIE) with the same Client ID and Client Secret. Labels there carry a “Sample” watermark, and no money is charged. Turn the switch off before going live.

    How to create a UPS waybill from an order

    The general steps for all carriers are in how to create a waybill from an order.

    Where: an order card with the “UPS” delivery method → “Delivery” section → “Create waybill”.

    What the form fills in itself and what to check

    FieldSourceWhat to check
    Last name, First name, Phone, E-MailOrderPhone is required
    Postcode, City, Street, House, ApartmentThe order's delivery address: the whole address goes in “Street”, “House” and “Apartment” are emptyStreet, house and apartment together — up to 35 characters, city — up to 30; Elbuz truncates anything longer
    Country (ISO code: DE, FR, IT, ES…)The order's delivery countryNot recognized — the sender's country
    Total weight, kgWeight of the order's productsNo weight on the products either — 1 kg is sent; rounded to 0.1 kg
    Length, Width, Height, cmEmptySent only if all three are filled in
    Shipment descriptionCategory or list of productsUp to 50 characters
    Return delivery (recipient)“Money” if the order is unpaid and payment is on deliverySet “Not required”: UPS cash on delivery isn't connected
    UPS waybill creation form: recipient, address and shipment parameters
    1Recipient country (ISO code)
    2Total weight, kg
    3Length / Width / Height
    4Cash on delivery: Not required
    5Create waybill button
    1. Recipient country — two-letter ISO code, e.g. DE.
    2. Total weight of the parcel in kilograms.
    3. Parcel dimensions: length, width and height in centimetres.
    4. Cash on delivery for the recipient is set to Not required.
    5. Create waybill sends the request to UPS (not pressed during capture).

    The order number goes into the waybill as a reference, up to 35 characters. The sender pays — from your UPS account, with your own packaging. The form doesn't offer UPS Access Point pickup points: delivery is to an address only.

    What happens after “Create waybill”

    1. Elbuz checks the data before it goes to UPS. If the account number or sender address is missing, you get a message with the reason, for example “Error: UPS account number is required (API settings)”; the waybill isn't created.
    2. UPS creates the shipment. The parcel tracking number goes into “Delivery service: number”, and you see “Waybill created, No.‹number›”.
    3. If UPS refuses, the window shows its text with the code in brackets, and the order stays without a number.

    To get a tracking link in the order, fill in “Tracking link” in the “UPS” delivery method, for example https://www.ups.com/track?loc=pl_PL&tracknum= (delivery methods).

    The waybill is created right away and charged at the UPS rate. You can't cancel or change it from Elbuz — only in UPS. After canceling, clear “Delivery service: number” in the order to create a new one.

    How to print a UPS label

    Where: order card → “View waybill” → print icon; or “Shipments” → row → “Print waybill”.

    The label opens in a new tab as a GIF image. Elbuz fetches it from UPS by waybill number each time, so you can also reprint a waybill whose number was entered manually. UPS keeps label copies for 90 days (UPS help).

    How to order a UPS courier

    Where: order card → “View waybill” → the “Courier pickup” block.

    • “Pickup date” — the next business day by default.
    • “Pickup from” and “to” — if empty: 09:00–17:00.
    • “Parcels, pcs” and “Total weight, kg” — how much to collect.

    “Order a courier” → “Courier ordered #‹number›”. The UPS request number (PRN) is saved in the order; the pickup address is the connection's “Sender” block.

    In Poland, a one-off UPS pickup is paid: one fee per visit, regardless of the number of parcels (UPS terms). A daily pickup is set up in your UPS account — then no requests are needed.

    How Elbuz tracks UPS parcels

    Every 10 minutes Elbuz asks UPS about parcels — up to 100 waybills per run. It tracks orders from the last 60 days and orders in the marked statuses until the parcel reaches the “Delivered” state. The UPS status code and text show in the order and in “Shipments”.

    In “Shipments”, UPS supports “Print waybill”, “SMS to recipient” and “Track on carrier site” — the ups.com page with the parcel number.

    How to change order statuses by UPS codes

    Elbuz enters the UPS codes in “Delivery statuses” itself. A code that isn't in the table gives the “Unknown” state in “Shipments”, and the order status doesn't change on it.

    1. In the UPS connection, open the “Order statuses for which to check the parcel status with the delivery service” block. Mark the statuses in which an order awaits delivery, for example “Shipped”.
    2. In the “Notification settings” block, open “Delivery statuses” (and “Order statuses”, “Payment statuses” if needed).
    3. The UPS codes from the table below are already in the “Code (name) on site (API)” column; add your own comma-separated.
    UPS codes for the “Delivery statuses” window
    Your delivery statusUPS codeState in “Shipments”
    Awaiting senderM — UPS has received the shipment dataCreated
    On the wayI — in transit, including out for delivery; P — picked upIn transit
    DeliveredDDelivered, polling stops
    RefusedRS — returned to shipperRefused, polling stops

    Without code D next to “Delivered” in “Delivery statuses”, the parcel never reaches the “Delivered” state. Elbuz keeps asking about it after delivery, using up the limit of 100 waybills per run.

    Leave the exception code X and the voided shipment code MV out of the table: such a parcel will be “Unknown”, and you'll notice it. The codes are from the UPS tracking reference. How the three status tables work is explained in the article on automatic order status changes.

    Scenarios

    A risk-free first connection

    Enter the keys and account number, turn on “Sandbox environment”. Create a waybill on your own order and print the label with the “Sample” watermark. If everything is fine, turn the switch off.

    Daily shipping across the EU

    “Default service” — UPS Standard. From each order — “Create waybill” and print the label. Order the courier with one request per day, or set up a daily pickup in UPS.

    Orders close by themselves

    Mark the “Shipped” status in the connection. Enter code D next to “Delivered” in both “Delivery statuses” and “Order statuses”. Once the parcel is delivered, the order moves to “Delivered”, and Elbuz stops asking about it.

    What to do when something goes wrong

    Common problems
    What you seeWhyWhat to do
    “The delivery service is not connected: fill in its API settings…” The Client Secret isn't entered or “Active” is off Fill in “Password” and turn on “Active” (what to enter)
    “UPS OAuth: …” UPS didn't accept the Client ID or Client Secret Copy the keys again from “My Apps” on developer.ups.com
    “UPS account number is required (API settings)” “UPS account number (Shipper Number)” is empty Enter the account number
    “sender address and phone are required (API settings)” The “Sender” block is missing the name, street, city, postcode or phone Fill in “Sender” in the connection
    “name and phone are required for recipient” or “address is required for recipient” The order has no recipient name, phone, street, city or postcode Add them in the waybill form
    “cash on delivery is not supported for UPS yet — choose «without COD»” “Return delivery (recipient)” is set to “Money” Choose “Not required”
    A UPS parcel is “Unknown” in “Shipments” The UPS code isn't in the “Delivery statuses” window Add the code (UPS codes)

    FAQ

    How much does the UPS integration in Elbuz cost?

    Elbuz charges nothing for UPS waybills, labels or statuses. The UPS API is free on the Community plan; you pay UPS for delivery and the courier.

    Can I ship UPS from outside Poland?

    Yes, from any EU country: enter the country code in the “Sender” block's country field. Elbuz doesn't send customs data, so shipments stay within the EU.

    Can I send UPS with cash on delivery from Elbuz?

    No, UPS cash on delivery isn't connected: a waybill with “Money” is rejected. Leave “Not required” or arrange such a parcel in UPS.

    How do I cancel a UPS waybill?

    Only in UPS. Then clear “Delivery service: number” in the order (after creation).

    Can I choose a UPS service for a single waybill?

    No, there is one service for all — “Default service” in the connection. Switch it before a waybill of another type.

    Why doesn't the UPS status change the order status?

    The order status isn't marked in the connection, or the UPS code isn't in the table. Mark the status and enter the codes (UPS codes).

    Where to find it and who has access

    Menu
    Account → System settings → Other settings → External services and integrations → Delivery → UPS
    Other ways in
    Directories → Documents → Shipments → “Delivery services”; order card → “Delivery” section
    Access right
    connection — “API & access tokens”; waybill and courier — the “Delivery waybill creation” window
    Prepare
    a UPS account with an account number (Shipper Number) and an application on developer.ups.com
    1. Create an application and keysdeveloper.ups.com
    2. Enter the keys, account number and senderExternal services and integrations → UPS
    3. Enter the UPS status codesSame place, “Notification settings”
    4. Create a waybill and print the labelOrder card, “Delivery” section
    5. Order a courierView waybill

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free