Create International Consignment

This API is used to create cargo and logistics shipments from Turkey to abroad. The sender address must be in Turkey, and the recipient address must be abroad.

Endpoint Information

Property Value
URL {{BASE_URL}}/api/v1/consignments
HTTP Method POST
Content Type application/json
Authentication APIKEY header
Rate Limit 300 requests / 1 minute (sliding window)

Rate Limit Exceeded: When the limit is exceeded, the API returns a 429 Too Many Requests error. For details, see Rate Limit.

Idempotency: This endpoint supports duplicate request protection. For details, see Idempotency.


Quick Start

To create an international consignment, you need the following basic information:

Requirement Description
API Key API key assigned to your account
Provider Selection Determining the carrier with provider_id or preference
Sender Information Name, address, phone, tax number (Turkey address)
Recipient Information Name, address, phone (International address)
Package Information Weight, dimensions, HS code, country of origin, unit price
Incoterms Customs delivery terms (DDP, DDU, DAP)

Minimal Request Example

Below is the simplest international consignment creation request containing only the required fields:

{
    "provider_id": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "incoterms_type": 1,
    "consignor": {
        "name": "Sender Company",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34700",
        "address": "Sender address",
        "phone_number": "+902161234567",
        "tax_number": "1234567890"
    },
    "consignee": {
        "name": "Receiver Name",
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "postal_code": "10115",
        "address": "Receiver address",
        "phone_number": "+4930123456"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 1,
            "length": 20,
            "width": 15,
            "height": 10,
            "dangerous_goods": false,
            "items": [
                {
                    "description": "Electronic Accessory",
                    "gtip": "854370900000",
                    "origin": "TR",
                    "currency_code": "EUR",
                    "unit_price": 25.00,
                    "quantity": 1
                }
            ]
        }
    ]
}

Fields Specific to International Consignments

Incoterms (Customs Delivery Terms)

The incoterms_type parameter determines who is responsible for customs duties and delivery.

Value Code Description
1 DDP Delivered Duty Paid - Customs duties belong to the sender. The recipient makes no additional payment.
2 DDU Delivered Duty Unpaid - Customs duties belong to the recipient. Default value.
3 DAP Delivered at Place - Same as DDU. Customs duties belong to the recipient.

State Code

For shipments to the USA, Canada, and Ireland, the state_code field is required.

Country Example state_code
USA (US) CA (California), NY (New York), TX (Texas)
Canada (CA) ON (Ontario), BC (British Columbia), QC (Quebec)
Ireland (IE) D (Dublin), CO (Cork)
{
    "consignee": {
        "country": "US",
        "state": "California",
        "state_code": "CA",
        "city": "Los Angeles",
        "postal_code": "90001"
    }
}

HS Code (Harmonized System Code)

For international shipments, the gtip (HS code) is required for each product. This code determines the customs classification of the product.

Product Category Example HS Code
Electronic accessories 854370900000
Textile products 620520000000
Food products 170490999019
Cosmetics 330499900000

HS Code Search: You can use the HS Code Search API to find the correct HS code.

Post Type (Shipment Type)

For international shipments, the post_type field is required. This field determines the customs declaration type of the shipment.

Value Code Description
1 SAMPLE Sample shipment
2 MICRO Micro Export (ETGB) - Commercial shipments under 15,000 EUR
3 GIFT Gift shipment
4 SALE Sale - Recommended for e-commerce shipments
5 PERSONAL Personal shipment
6 OTHER Other
7 DOCUMENT Document - Non-commercial papers

E-commerce Tip: Use SALE (4) for online sales shipments or MICRO (2) for shipments under micro export scope.

E-Archive Invoice Requirement

For commercial international shipments, e-archive invoice upload is required:

Post Type Code E-Archive Invoice
2 MICRO (Micro Export) Required
4 SALE (Sale) Required

You need to upload the invoice to the system before creating the consignment and use the returned id value in the consignment request.

Step Action Description
1 Upload E-Archive Invoice Upload the invoice using Document Upload API
2 Get Document ID Store the id value returned in the response
3 Create Consignment Create the consignment by adding the document ID to the documents array

Adding document to consignment request:

{
    "packages": [
        {
            "post_type": 2,
            ...
        }
    ],
    "documents": [
        {
            "id": 12345
        }
    ]
}

Important: If you try to create a consignment without uploading an e-archive invoice for micro export and sale shipments, the carrier may reject your shipment. For detailed information, see the Document Upload page.

EORI Number

For commercial shipments to European Union countries, the eori_number field is recommended. EORI (Economic Operators Registration and Identification) is a unique identifier used in EU customs procedures.

{
    "consignor": {
        "name": "Anadolu Technology Inc.",
        "tax_number": "1234567890",
        "eori_number": "TR1234567890123"
    }
}

Shipping Method Selection (PTT Abroad)

When creating international shipments with PTT Abroad, you can select Air Parcel or Surface Parcel shipping method using the specific_shipping_method parameter.

Value Description Delivery Time
pttabroad_air_parcel Air Parcel - Air transport Faster (5-10 business days)
pttabroad_ground_parcel Surface Parcel - Land/sea transport More economical (15-45 business days)

Note: This parameter is only valid for the PTT Abroad provider. If not specified, Air Parcel is used by default.

Example Usage:

{
    "provider_id": 7,
    "specific_shipping_method": "pttabroad_ground_parcel",
    "consignor": { ... },
    "consignee": { ... },
    "packages": [ ... ]
}

IOSS Number (Import One-Stop Shop)

IOSS number can be used for e-commerce shipments under 150 EUR to the European Union. IOSS allows the seller to pay VAT on behalf of the buyer, speeding up customs processes.

Important: The IOSS number is not sent in the API request. This number is defined as a customer parameter in the system and is automatically added to all your international shipments.

To define an IOSS number: Contact the ComToHome support team to request that the ioss_number parameter be defined on your account.

Property Description
Scope B2C shipments under 150 EUR to EU countries
Advantage Recipient pays no VAT at customs, delivery is faster
Definition As a customer parameter via the panel

Optional Headers

Label Format (X-Label-Format)

You can specify the format of the shipping label returned when the consignment is created using the X-Label-Format header.

Header Value Description
X-Label-Format application/pdf Default. Returns label in PDF format
X-Label-Format application/zpl Returns label in ZPL format. Ideal for thermal printers

Request Parameters

Basic Parameters

Parameter Name Parameter Type Required Description
preference Integer CONDITIONAL Carrier preference. Required if provider_id is not specified. Available Values
provider_id Integer CONDITIONAL Carrier ID. Required if preference is 0. Available Values
address_resolver_type Integer REQUIRED Address resolution type. Default: 0. Detailed Information
reference_no String (MAX 255) OPTIONAL Reference number
invoice_number String (MAX 255) OPTIONAL Invoice number
incoterms_type Integer OPTIONAL Customs delivery terms. Default: 2 (DDU). Available Values
specific_shipping_method String (MAX 255) OPTIONAL Provider shipping method. Available Values
generate_provider_barcode Bool OPTIONAL Automatic barcode assignment. Default: false
specific_provider_barcode String (MAX 255) OPTIONAL Custom barcode definition
is_pickup_requested Bool OPTIONAL Courier pickup request. If true, an automatic courier request is created for the consignment. Default: false

Sender Information

Parameter Name Parameter Type Required Description
consignor.name String (MAX 255) REQUIRED Sender name
consignor.attention_name String (MAX 255) OPTIONAL Sender alternate name
consignor.country String (2-3 CHAR) REQUIRED Country code (TR)
consignor.state String (MAX 100) REQUIRED State/Province
consignor.city String (MAX 100) REQUIRED City/District
consignor.postal_code String (MAX 30) OPTIONAL Postal code
consignor.address String (MAX 1000) REQUIRED Full address
consignor.phone_number String (MAX 20) OPTIONAL Phone number
consignor.email String (MAX 255) OPTIONAL Email address
consignor.tax_number String (MAX 255) OPTIONAL Tax number (recommended for international)
consignor.eori_number String (MAX 255) OPTIONAL EORI number (recommended for EU countries)
consignor.state_code String (MAX 255) CONDITIONAL State code (required for USA, Canada, Ireland)

Recipient Information

Parameter Name Parameter Type Required Description
consignee.name String (MAX 255) REQUIRED Recipient name
consignee.attention_name String (MAX 255) OPTIONAL Recipient alternate name
consignee.country String (2-3 CHAR) REQUIRED Country code (ISO2/ISO3)
consignee.state String (MAX 100) REQUIRED State/Province
consignee.city String (MAX 100) REQUIRED City
consignee.postal_code String (MAX 30) OPTIONAL Postal code
consignee.address String (MAX 1000) REQUIRED Full address
consignee.phone_number String (MAX 20) OPTIONAL Phone number
consignee.email String (MAX 255) OPTIONAL Email address
consignee.tax_number String (MAX 255) OPTIONAL Tax number
consignee.eori_number String (MAX 255) OPTIONAL EORI number
consignee.state_code String (MAX 255) CONDITIONAL State code (required for USA, Canada, Ireland)

Package Information

Parameter Name Parameter Type Required Description
packages.reference_no String (MAX 255) OPTIONAL Package reference number
packages.package_type Integer REQUIRED Package type. 1 (Box) or 2 (Envelope) Available Values
packages.provider_packaging_type String OPTIONAL Provider specific packaging type
packages.post_type Integer REQUIRED Post type Available Values
packages.weight Float REQUIRED Package weight (kg). Minimum: 0.01
packages.length Float REQUIRED Package length (cm)
packages.width Float REQUIRED Package width (cm)
packages.height Float REQUIRED Package height (cm)
packages.dangerous_goods Boolean REQUIRED Contains dangerous goods?
packages.items Array REQUIRED Package content list (at least 1 item)

Package Content Information

Parameter Name Parameter Type Required Description
packages.items.description String (MAX 255) REQUIRED Product description (English recommended)
packages.items.gtip String (MAX 16) REQUIRED HS code (Customs tariff number)
packages.items.origin String (2-3 CHAR) REQUIRED Country of origin code
packages.items.currency_code String (3 CHAR) REQUIRED Currency (EUR, USD, GBP etc.)
packages.items.unit_price Float REQUIRED Unit price. Minimum: 0
packages.items.quantity Integer REQUIRED Quantity. Minimum: 1
packages.items.category String (MAX 255) OPTIONAL Category
packages.items.weight Float OPTIONAL Product weight (kg). Minimum: 0.01

Document Information (Optional)

This field is completely optional and should not be used if your consignment will not contain documents.

Document upload is required before shipping. For this process, please refer to: Consignment Document Upload API.

Parameter Name Parameter Type Required Description
documents.id Integer REQUIRED Previously uploaded document ID

Special Services Information (Optional)

This field is completely optional and should not be used if your consignment does not include special services.

For more information about the Special Service Types and Detail parameters in the system, please refer to: Special Services

Parameter Name Parameter Type Required Description
special_services.service_type String REQUIRED Service type (e.g., INSURANCE, SIGNATURE_REQUIRED)
special_services.details.$dynamic Dynamic CONDITIONAL Dynamic parameters for each service type

Example Usage

Full Request Example (All Languages)

Below are comprehensive API request examples for different programming languages.

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -d '{
    "provider_id": 7,
    "preference": 0,
    "address_resolver_type": 0,
    "incoterms_type": 2,
    "reference_no": "SIP-20241217-EU-001",
    "consignor": {
        "name": "Anadolu Technology Inc.",
        "attention_name": "Export Department",
        "country": "TR",
        "state": "İstanbul",
        "city": "Kadıköy",
        "postal_code": "34710",
        "address": "Moda Caddesi No:45 Kat:3 Caferağa Mahallesi",
        "phone_number": "+902163456789",
        "email": "export@anadolutech.com",
        "tax_number": "1234567890",
        "eori_number": "TR1234567890123"
    },
    "consignee": {
        "name": "Hans Mueller",
        "attention_name": "Hans Mueller",
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "postal_code": "10115",
        "address": "Friedrichstrasse 123, Mitte",
        "phone_number": "+493012345678",
        "email": "hans.mueller@example.de"
    },
    "packages": [
        {
            "package_type": 1,
            "post_type": 4,
            "weight": 0.85,
            "length": 25,
            "width": 20,
            "height": 10,
            "dangerous_goods": false,
            "items": [
                {
                    "description": "Wireless Bluetooth Headphones",
                    "gtip": "851830000000",
                    "origin": "TR",
                    "currency_code": "EUR",
                    "unit_price": 79.99,
                    "quantity": 1,
                    "category": "Electronics"
                }
            ]
        }
    ]
}'

API Response

On a successful request, the API will return a response like this:

{
    "status": true,
    "message": "Consignment created successfully",
    "data": {
        "consignment": 632279,
        "barcode": "C2H46282802942",
        "c2hBarcode": "C2H46282802942",
        "providerTrackingCode": "1Z999AA10123456784",
        "trackingUrl": "https://provider.com/track/1Z999AA10123456784",
        "contentType": "application/pdf",
        "base64label": "...base64data",
        "detail": {
            "total_cost": 245.50,
            "currency_code": "TRY",
            "currency_rate": 1,
            "reference_no": "SIP-20241217-EU-001",
            "packages": {
                "desi": 1.13,
                "weight": 0.85,
                "quantity": 1
            }
        }
    }
}

Response Fields

Field Type Description
status Boolean Operation success status
message String Operation result message
data.consignment Integer Created consignment ID
data.barcode String Barcode assigned by the carrier
data.c2hBarcode String ComToHome system barcode
data.providerTrackingCode String Carrier tracking code
data.trackingUrl String Cargo tracking page URL
data.contentType String Label file format
data.base64label String Base64 encoded shipping label
data.detail.total_cost Float Total shipping cost
data.detail.currency_code String Currency

Error Responses

If the API request fails, the API will return an error response like this:

{
    "status": false,
    "errors": [
        {
            "message": "This value should not be blank.",
            "field": "packages[0].items[0].gtip"
        },
        {
            "message": "This value should not be blank.",
            "field": "packages[0].items[0].origin"
        }
    ]
}

Common Error Scenarios

Error Message Field Description Solution
[referenceNo] Reference number is already in use. reference_no The same reference has been used before Use a unique reference number
This value should not be blank. packages.items.gtip etc. Required field is empty Fill in the relevant field
State code is required. consignee.state_code state_code missing for USA/Canada/Ireland Add the relevant state code
The carrier does not support shipping to this country. consignee.country Provider does not support the destination country Select a different provider
Only BOX, ENVELOPE enums are allowed. packages.package_type Invalid package type Use 1 (Box) or 2 (Envelope)

Next Steps

After the consignment is successfully created:

  1. Print Label: Decode the base64label field to print the label
  2. Customs Documents: Create CN22 or CN23 if needed
  3. Proforma Invoice: Create Proforma Invoice
  4. Tracking: Track the consignment using trackingUrl or c2hBarcode
  5. Webhook: Set up Webhook to automatically receive consignment status changes