Skip to main content

Frequently Asked Questions (FAQ)

This page provides answers to common questions about the Shipping Channels API.

General Questions​

Q: What is the Shipping Channels API?​

A: The Shipping Channels API allows you to integrate your applications with various shipping providers, enabling you to create shipments, generate labels, track parcels, and manage webhooks programmatically through a unified interface.

Q: Which shipping providers are supported?​

A: We currently support 13 shipping providers:

ProviderCountries
PPLCzech Republic, Slovakia
DHLWorldwide
DHL PolandPoland, International
DPDMultiple European countries
DPD PolandPoland
GLSMultiple European countries
GLS PolandPoland, EU
SPX (Shopee Express)Southeast Asia, Central Europe
MRWSpain, Portugal
Poste ItalianeItaly, Europe, USA, Canada
AllegroPoland
BaselinkerMultiple (via integrated couriers)
OneDeliveryCzech Republic, Slovakia

For detailed configuration, see the Shipping Providers documentation.

Q: How do I get an API key?​

A: You can generate and manage your API keys from your account dashboard. Please refer to the Authentication Guide for detailed instructions.

Q: Is there a rate limit for API requests?​

A: Yes, rate limits are enforced to ensure fair usage and stability of the API. Please refer to the Rate Limits for more information.

Shipping Channels​

Q: What is a shipping channel?​

A: A shipping channel is a configured connection to a shipping provider with your credentials. Each channel stores provider-specific settings like API keys, account numbers, default label format, and COD configuration. You can have multiple channels for the same provider with different configurations.

Q: How do I create a shipping channel?​

A: You can create shipping channels through the API or the dashboard. Each channel requires:

  1. A unique name for identification
  2. Provider selection (e.g., ppl, dhl, dpd)
  3. Provider-specific credentials

See the Shipping Channels Guide for details.

Q: What are shipping channel statuses?​

A: Shipping channels can have these statuses:

  • pending_validation - Newly created, awaiting validation
  • active - Validated and working correctly
  • inactive - Manually disabled by the user
  • error - Failed validation or encountered an error

Shipments​

Q: What information do I need to create a shipment?​

A: To create a shipment, you need:

  • shipping_channel_id - ID of an active shipping channel
  • label_format - Desired label format (pdf or zpl)
  • sender_contact - Sender's contact information
  • recipient_contact - Recipient's contact information
  • origin_address - Origin address
  • destination_address - Destination address
  • parcels - Array of parcel objects with dimensions and weight

For international shipments, customs_declaration may also be required. Refer to the Create Shipment API Reference for a complete list of parameters.

Q: Can I create multi-parcel shipments?​

A: Yes, you can create shipments with multiple parcels (up to 50 parcels depending on the provider). Simply include multiple objects in the parcels array. Each parcel will receive its own tracking number from the shipping provider.

{
  "parcels": [
    {
      "parcel_type": "package",
      "length_dimension": 30,
      "width_dimension": 20,
      "height_dimension": 15,
      "dimension_unit": "CM",
      "weight_amount": 2.5,
      "weight_unit": "KG"
    },
    {
      "parcel_type": "package",
      "length_dimension": 40,
      "width_dimension": 30,
      "height_dimension": 20,
      "dimension_unit": "CM",
      "weight_amount": 5.0,
      "weight_unit": "KG"
    }
  ]
}

Q: How do I add Cash on Delivery (COD) to a shipment?​

A: Add the cash_on_delivery_amount and cash_on_delivery_currency fields at the shipment level:

{
  "shipping_channel_id": "ch_123456",
  "label_format": "pdf",
  "cash_on_delivery_amount": 150.00,
  "cash_on_delivery_currency": "CZK",
  ...
}

Note: Not all providers support COD. Check the provider-specific documentation for details.

Q: How do I add insurance to a shipment?​

A: Add the insurance_amount and insurance_currency fields at the shipment level:

{
  "insurance_amount": 500.00,
  "insurance_currency": "EUR"
}

Q: Can I track a shipment created via the API?​

A: Yes, every shipment created via the API automatically creates tracking parcels for each parcel in the shipment. You can use the Tracking Parcels API to monitor their status, or check the parcels array in the shipment response which includes tracking_parcel information.

Labels​

Q: What label formats are supported?​

A: The API supports two label formats:

  • pdf - Standard PDF format for office printers
  • zpl - Zebra Programming Language for thermal label printers

Some providers may support additional formats (e.g., EPL). Check the provider-specific documentation for details.

Q: How do I download a shipping label?​

A: After successfully creating a shipment, download the label using the Download Label endpoint:

GET /v1/shipments/{id}/label

The response contains the label as base64-encoded content in the label.content field.

Q: How do labels work for multi-parcel shipments?​

A: For multi-parcel shipments, the label download returns a single combined file containing all parcel labels:

  • PDF: Each parcel's label is on a separate page
  • ZPL: Labels are concatenated

Tracking​

Q: What tracking statuses are available?​

A: Tracking parcels can have these statuses:

StatusDescription
createdTracking parcel has been created
waiting_for_shipmentWaiting to be handed over to carrier
in_transitShipment is on its way
out_for_deliveryOut for delivery
deliveredSuccessfully delivered
delivered_with_exceptionDelivered with an issue
ready_for_pickupReady for pickup at location
returnedReturned to sender
cancelledShipment cancelled
on_holdOn hold, awaiting action
delayedShipment is delayed
customsCurrently in customs
damagedShipment has been damaged
errorError occurred during tracking
not_recognizedTracking number not yet recognized

Q: How often are tracking statuses updated?​

A: The platform polls shipping providers regularly to update tracking statuses. The frequency depends on the provider, but updates typically occur within minutes to hours of the actual status change.

Webhooks​

Q: What are webhooks and how do they work?​

A: Webhooks are automated notifications sent by the API to a URL you provide when specific events occur. This allows you to receive real-time updates without constantly polling the API. Learn more in the Webhooks Guide.

Q: What webhook events are available?​

A: Available webhook events include:

EventDescription
shipping_channel.createdShipping channel created
shipping_channel.updatedShipping channel updated
shipping_channel.deletedShipping channel deleted
shipping_channel.validatedShipping channel validated
shipping_channel.status_changedShipping channel status changed
tracking_parcel.createdTracking parcel created
tracking_parcel.updatedTracking parcel updated
tracking_parcel.deletedTracking parcel deleted
tracking_parcel.status_changedTracking parcel status changed
shipment.createdShipment created
shipment.updatedShipment updated
shipment.deletedShipment deleted
shipment.status_changedShipment status changed

Q: How do I verify webhook payloads?​

A: Verify webhook payloads using the signature in the X-Shipping-Channels-Signature header. The signature is an HMAC SHA-256 hash of the request body using your webhook secret. Details on signature verification can be found in the Webhooks Guide.

Q: What happens if my webhook endpoint is down?​

A: If your webhook endpoint is temporarily unavailable or returns an error, the API will retry delivery with exponential backoff for up to 24 hours. Monitor webhook delivery attempts using the Webhook Subscription Logs API.

Troubleshooting​

Q: I'm getting a 401 Unauthorized error. What should I do?​

A: This usually means your API key is missing or invalid. Ensure you are including your API key in the Authorization header as Bearer YOUR_API_KEY. Double-check your API key for typos. Refer to the Authentication Guide for more details.

Q: My API request is returning a 422 Unprocessable Entity error. How can I fix it?​

A: A 422 error indicates validation issues with your request. The API response will include an errors object detailing which fields failed validation and why. Common causes:

  • Missing required fields (e.g., label_format, parcels)
  • Invalid field values (e.g., invalid country code, negative weight)
  • Provider-specific validation errors

See the Error Handling Guide for more information.

Q: I'm getting a "COD variable symbol is required" error with PPL.​

A: When using Cash on Delivery with PPL, you must provide a variable symbol. Either:

  • Include metadata.cod_variable_symbol in your shipment request
  • Configure defaultCodVarSym in your PPL channel settings

Q: My shipment was created but has no label.​

A: Check the is_successful and has_label fields in the shipment response. If is_successful is false, there was an error creating the shipment with the provider. Check the error messages in the response. Common causes:

  • Invalid credentials in the shipping channel
  • Provider API unavailable
  • Validation errors (address, weight limits, etc.)

Q: I'm encountering a 500 Internal Server Error. What does this mean?​

A: A 500 error indicates an unexpected issue on our server. If this error persists, please contact our support team with:

  • The request URL and method
  • The request body (with sensitive data redacted)
  • The full error response
  • The timestamp of the request

Q: The provider rejected my shipment. How do I find out why?​

A: Check the shipment response for error details. The error_message field on parcels or the shipment itself will contain provider-specific error messages. Common issues include:

  • Invalid or incomplete address
  • Weight or dimension limits exceeded
  • Unsupported destination country
  • Missing required fields for the provider

International Shipments​

Q: What additional information is needed for international shipments?​

A: International shipments require a customs_declaration object containing:

  • export_reason - Reason for export (sale, gift, sample, etc.)
  • shipment_date - Date of shipment for customs
  • items - Array of items with quantity, value, origin country, and HS codes

Optional fields include sender/receiver tax numbers, EORI numbers, and IOSS registration numbers.

Q: What are HS codes and where do I find them?​

A: HS (Harmonized System) codes are 8-digit codes that classify products for customs purposes. You can find HS codes through your country's customs authority website or use online HS code lookup tools. The code should accurately describe the product being shipped.

If you have a question that is not answered here, please contact our support team.