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.
| 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.
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) |
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
}
]
}
]
}
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. |
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"
}
}
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.
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.
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.
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"
}
}
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 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 |
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 |
| 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 |
| 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) |
| 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) |
| 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) |
| 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 |
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 |
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 |
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"
}
]
}
]
}'
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
}
}
}
}
| 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 |
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"
}
]
}
| 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) |
After the consignment is successfully created:
base64label field to print the labeltrackingUrl or c2hBarcode