Temu Courier Integration with Voila

This document provides a step-by-step guide to integrating Temu with Voila.

Last updated 1 day ago

Temu Courier Integration Tutorial

Temu sellers are fast; your labels should be faster. This guide shows you how to plug Temu Buy Shipping into the Voila API so you can fetch services and generate shipping labels automatically for your Temu marketplace orders.

What this integration does

This tutorial walks you through how to use Temu Buy Shipping via the Voila API to create and print shipping labels for Temu marketplace orders. By the end, you’ll be able to authenticate, fetch available Temu services, and generate labels programmatically.

By the end, you’ll be able to:

Authenticate Temu against a Voila API User.
Fetch available Temu services for an order.
Generate labels and pull down the PDF.

Region supported: EU (European Union).

Prerequisites

Before you start wiring things together, make sure you have:

An active Voila account with access to API Accounts.
An active Temu seller account.
Temu API credentials from the Temu Partner Platform: ‎`app_key`, ‎`app_secret`, ‎`access_token`.
At least one Temu order with status “Pending Shipment” (status = 2).

Once you have these, you’re ready to move from “thinking about labels” to “creating labels”.

Step 1 – Set up or access your Voila API Account

Click here to log in to the Voila ↗.
From the left sidebar, go to API Accounts.
Either:
- Select an existing API User you want to use for Temu, or
- Click Create API User and provide:
  - Name: e.g. ‎`temu-production`
Click Create, then immediately note down:
- API User Name (e.g. ‎`temu-production`)
- Account Key
- API Token (create one if none exists)

You’ll use API User Name and API Token in the request headers for all Temu label calls.

Step 2 – Register Temu as a courier for that API User

In the API Accounts page, locate your chosen API User.
In the Registered Auth column, click the + icon.
In the modal:
- Choose Temu from the courier dropdown.
- Fill in the Temu credentials:
  - Company Name: A friendly identifier, e.g. ‎`MyTemuStore`
  - ‎`app_key`: Your Temu application key
  - ‎`app_secret`: Your Temu application secret
  - ‎`access_token`: Your Temu OAuth access token
Click Save.
To verify, click View in the Registered Auth column and confirm Temu appears in the list.

The Company Name you enter here is critical: if you provide one, you must send it as ‎`auth_company` in your API requests.

Step 3 – (Optional) Get available Temu shipping services

Before deciding which service to use, you can ask Temu which carriers/channels are available for a specific order. This is handy when you want Voila to return a list of options instead of hard‑coding a carrier and channel.

3.1 Request: Get services only

Endpoint:

`POST https://app.heyvoila.io/api/Temu/create-label`

Headers:

‎`api-user`: your API User Name (e.g. ‎`temu-production`)
‎`api-token`: your API Token
‎`Content-Type`: ‎`application/json`

Example request body to fetch services:

Example
{
  "auth_company": "MyTemuStore",
  "shipment": {
    "order_id": "PO-210-00485674593911312",
    "collection_date": "2026-01-15",
    "parcels": [
      {
        "dim_length": 30,
        "dim_width": 20,
        "dim_height": 10,
        "dim_unit": "cm",
        "items": [
          {
            "weight": 0.5,
            "weight_unit": "kg"
          }
        ]
      }
    ],
    "courier": {
      "get_services": true
    }
  }
}

3.2 Response: Services list

You’ll receive something like:

Example
{
  "available_services": [
    {
      "shipCompanyId": 1001,
      "shipCompanyName": "DHL Express",
      "channelId": 2001,
      "channelName": "DHL Express EU"
    },
    {
      "shipCompanyId": 1002,
      "shipCompanyName": "DPD",
      "channelId": 2002,
      "channelName": "DPD Standard"
    }
  ],
  "unavailable_services": [],
  "warehouse_id": "WH123",
  "hint": "Use ship_company_id and channel_id in courier specifics."
}

Record the ‎`shipCompanyId` and ‎`channelId` for the services you intend to use in production. You’ll use these either directly in your requests or when building presets.

Step 4 – (Optional but recommended) Create Temu service presets

Service presets let you save courier‑specific settings and reuse them just by sending a ‎`dc_service_id` in your API calls. This keeps your integration cleaner and makes it easy to switch or add services later.

4.1 Create a Temu preset

In the Voila sidebar, go to Couriers → Service Presets.
Search for Temu and select it.
Choose the API Account you set up earlier.
Click Create Preset and fill in:
- Name: e.g. ‎`Temu DHL Express EU`
- DC Service ID: a unique ID you’ll send from your system, e.g. ‎`TEMU-DHL-EU`
- Optional notes (for your own reference)
In the courier‑specific section, you can configure:
- warehouse_id` – Temu warehouse ID (use default if omitted)
- ‎`ship_company_id` – from ‎`get_services`
- ‎`channel_id` – from ‎`get_services`
- ‎`retry_shipment` – whether to auto‑retry failed shipments
- ‎`get_services` – set ‎`true` for a “services only” preset
- ‎`send_type` – ‎`0` single package (default), ‎`1` multi‑package, ‎`2` merge orders
Configure Transit Times (required):
- Choose countries for each zone.
- Set min and max transit days per zone.

Save the preset when you’re done.

4.2 Example preset patterns

Some useful presets you might configure:

Get services only:
- Name: ‎`Temu - Get Services`
- ‎`dc_service_id`: ‎`TEMU-GET-SERVICES`
- ‎`get_services`: ‎`true`
Fixed carrier/channel (e.g. DHL Express EU):
- Name: ‎`Temu DHL Express EU`
- ‎`dc_service_id`: ‎`TEMU-DHL-EU`
- ‎`ship_company_id`: ‎`1001`
- ‎`channel_id`: ‎`2001`
Multi‑package / merged orders:
- Multi‑package: ‎`send_type = 1`
- Merge orders: ‎`send_type = 2`

Step 5 – Create a Temu shipping label

Once your API user and Temu auth are set up, you can start generating labels.

Endpoint:

‎`POST https://app.heyvoila.io/api/Temu/create-label`

Headers:

‎`api-user`: your API User Name
‎`api-token`: your API Token
‎`Content-Type`: ‎`application/json`

5.1 Request using a specific service directly

If you don’t want to use a preset, you can send ‎`ship_company_id` and ‎`channel_id` inline:

Example
{
  "auth_company": "MyTemuStore",
  "shipment": {
    "order_id": "PO-210-00485674593911312",
    "collection_date": "2026-01-15",
    "parcels": [
      {
        "dim_length": 30,
        "dim_width": 20,
        "dim_height": 10,
        "dim_unit": "cm",
        "items": [
          {
            "weight": 0.5,
            "weight_unit": "kg"
          }
        ]
      }
    ],
    "courier": {
      "ship_company_id": 1001,
      "channel_id": 2001
    }
  }
}

OR, if your integration uses logistics types instead of channels:

Example
{
  "auth_company": "MyTemuStore",
  "shipment": {
    "order_id": "PO-210-00485674593911312",
    "collection_date": "2026-01-15",
    "parcels": [
      {
        "dim_length": 30,
        "dim_width": 20,
        "dim_height": 10,
        "dim_unit": "cm",
        "items": [
          {
            "weight": 0.5,
            "weight_unit": "kg"
          }
        ]
      }
    ],
    "courier": {
      "ship_company_id": 1001,
      "ship_logistics_type": 2001
    }
  }
}

Important behaviour:

‎`auth_company` must match the Company Name you used when registering Temu for this API User.
If you did not specify a Company Name when you registered auth, do not include ‎`auth_company` in the request at all.

In Voila:

When using the Courier Presets, the preset should contain ship_company_id and either (chanel_id OR ship_logistics_type).

5.2 Request using a preset (‎`dc_service_id`)

If you’ve set up a preset (recommended), you can simply reference it:

The preset should contain ship_company_id and either (chanel_id OR ship_logistics_type).

Example
{
  "auth_company": "MyTemuStore",
  "shipment": {
    "order_id": "PO-210-00485674593911312",
    "dc_service_id": "TEMU-DHL-EU",
    "collection_date": "2026-01-15",
    "parcels": [
      {
        "dim_length": 30,
        "dim_width": 20,
        "dim_height": 10,
        "dim_unit": "cm",
        "items": [
          {
            "weight": 0.5,
            "weight_unit": "kg"
          }
        ]
      }
    ]
  }
}

Preset values are automatically applied, but you can still override them by including fields in ‎`courier`.

5.3 Successful response

A successful label creation returns something like:

Example
{
  "type": "PDF",
  "request_id": "12345",
  "tracking_codes": ["TRACK123456789"],
  "tracking_urls": [null],
  "label_url": "https://s3.../label.pdf",
  "uri": "https://s3.../label.pdf",
  "courier_specifics": {
    "package_sn_list": ["PKG001"],
    "package_sn": "PKG001",
    "tracking_map": {
      "PKG001": "TRACK123456789"
    }
  }
}

From here, you can store the tracking code and label URL in your system and surface them wherever your users expect to see tracking details.

Step 6 – Download and print the Temu label

Take the ‎`label_url` from the response.
Open it in a browser or download it programmatically.
The label is a 4×6 inch PDF.

Printing guidelines:

Paper size: 4×6 inches (or A6)
Orientation: Portrait
Scale: 100% (no scaling)

If the label URL has expired (it’s valid for 1 hour), you can get a fresh link:

‎`GET https://app.heyvoila.io/api/pdfs/renew?key={label_key}`

Use the ‎`key` portion of the original URL.

Request field reference (for implementers)

Top-level fields:

‎`auth_company` (string, conditional): Company Name used when registering Temu.
‎`dc_service_id` (string, optional): ID of the service preset to apply.

‎``shipment`` object:

‎`order_id` (string): Temu parent order number, e.g. ‎`PO-210-00485674593911312`.
‎`collection_date` (date): ‎`YYYY-MM-DD`.
‎`parcels` (array, required): at least 1 parcel:
- ‎`dim_length`, ‎`dim_width`, ‎`dim_height` (numbers)
- ‎`dim_unit`: ‎`cm` or ‎`mm`
- ‎`items` (array, required, min 1):
  - ‎`weight` (number)
  - ‎`weight_unit`: ‎`kg`, ‎`g`, ‎`lb`, or ‎`oz`

Optional courier fields (either inline or via preset):

‎`warehouse_id` (string)
‎`ship_company_id` (integer)
‎`channel_id` (integer)
‎`get_services` (boolean)
‎`retry_shipment` (boolean)
‎`send_type` (integer: ‎`0`, ‎`1`, or ‎`2`)

Common errors and how to fix them

‎`API User not authenticated`
- Check ‎`api-user` header uses the User Name, not the key or token.
- Confirm ‎`api-token` is valid and the API User is enabled.
‎`No api-user set in header`
- Add ‎`api-user` header to the request.
‎`not authenticated for this courier`
- Temu credentials might be missing or ‎`auth_company` doesn’t match the Company Name from the Temu auth.
‎`Order has already been shipped`
- Temu status is 4 or 5; you cannot create another label.
‎`Order has been canceled`
- Temu status is 3; label creation is blocked.
‎`No shipping services available`
- Check weight and dimensions are valid for Temu’s constraints.

For authentication issues, run through:

‎`api-user` = API User Name.
‎`api-token` = valid token from the Tokens table.
Temu courier credentials registered and active.
‎`auth_company` exactly matches Company Name (if used).

Temu Courier Integration Tutorial

What this integration does

By the end, you’ll be able to:

Prerequisites

Before you start wiring things together, make sure you have:

Step 1 – Set up or access your Voila API Account

Step 2 – Register Temu as a courier for that API User

Step 3 – (Optional) Get available Temu shipping services

3.1 Request: Get services only

Endpoint:

Headers:

Example request body to fetch services:

3.2 Response: Services list

You’ll receive something like:

Step 4 – (Optional but recommended) Create Temu service presets

4.1 Create a Temu preset

4.2 Example preset patterns

Step 5 – Create a Temu shipping label

Endpoint:

Headers:

5.1 Request using a specific service directly

Important behaviour:

In Voila:

5.2 Request using a preset (‎`dc_service_id`)

5.3 Successful response

Step 6 – Download and print the Temu label

Printing guidelines:

If the label URL has expired (it’s valid for 1 hour), you can get a fresh link:

Request field reference (for implementers)

Top-level fields:

‎`shipment` object:

Optional courier fields (either inline or via preset):

Common errors and how to fix them

For authentication issues, run through:

‎``shipment`` object: