shipink-logo-vector-svgDocumentation

Shipments

Create, list, and delete shipments.

List shipments

Returns a paginated list of your shipments.

GET
/shipments

Authorization

AuthorizationBearer <token>

Authenticate using the access_token obtained from POST /token.

Format: Authorization: Bearer {access_token}

In: header

Query Parameters

page?integer

Page number

Default1
Range1 <= value
limit?integer

Number of items per page

Default10
Range1 <= value <= 100

Response Body

application/json

curl -X GET "https://api.shipink.io/shipments"
{
  "success": true,
  "meta": {
    "status": 200,
    "code": "NOT_FOUND",
    "message": "orders successfully received",
    "total": 100,
    "details": [
      {
        "field": "name",
        "error": "cannot be blank"
      }
    ]
  },
  "data": [
    {
      "id": "17ebb574-f53f-43c2-bcf6-8984f7fc100b",
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "order_id": "Nc220IyHvpV_",
      "carrier": {
        "shipment_id": "507855220681824288",
        "tracking_url": "https://kargo.aras.com.tr/track/507855220681824288",
        "invoice_id": "",
        "waybill_id": "",
        "carrier_id": "aras",
        "carrier_service_id": "aras_standart",
        "carrier_account_id": "efd4158f-75ca-4922-b8cc-c27e209db7e1",
        "shipment_type": "outgoing",
        "language": "tr",
        "settings": {
          "system_account": true,
          "denominator": 0,
          "is_marketplace": true,
          "label_id_range": "string",
          "label_support": true,
          "return_support": true,
          "payment_type": {
            "sender": true,
            "recipient": true,
            "cod_cash": true,
            "cod_credit": true
          }
        }
      },
      "content": "",
      "language": "tr",
      "note": "",
      "packages": [
        {
          "weight": 1,
          "weight_unit": "kg",
          "length": 20,
          "width": 15,
          "height": 10,
          "dimension_unit": "cm"
        }
      ],
      "sender": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "Ahmet Yılmaz",
        "tax_id": "",
        "tax_office": "",
        "company": "",
        "email": {
          "main": "user@example.com",
          "work": ""
        },
        "phone": {
          "main": "905321234567",
          "work": "",
          "cell": "",
          "code": ""
        },
        "address": {
          "street": "Example Street No:1",
          "city": "Maltepe",
          "city_code": "TR-34-108146",
          "state": "İstanbul",
          "state_code": "TR-34",
          "zip": "34857",
          "country": "Turkey",
          "country_code": "TR",
          "tax_id": "",
          "external_id": null,
          "status": ""
        },
        "return_address": {
          "street": "Example Street No:1",
          "city": "Maltepe",
          "city_code": "TR-34-108146",
          "state": "İstanbul",
          "state_code": "TR-34",
          "zip": "34857",
          "country": "Turkey",
          "country_code": "TR",
          "tax_id": "",
          "external_id": null,
          "status": ""
        }
      },
      "recipient": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "Ahmet Yılmaz",
        "tax_id": "",
        "tax_office": "",
        "company": "",
        "email": {
          "main": "user@example.com",
          "work": ""
        },
        "phone": {
          "main": "905321234567",
          "work": "",
          "cell": "",
          "code": ""
        },
        "address": {
          "street": "Example Street No:1",
          "city": "Maltepe",
          "city_code": "TR-34-108146",
          "state": "İstanbul",
          "state_code": "TR-34",
          "zip": "34857",
          "country": "Turkey",
          "country_code": "TR",
          "tax_id": "",
          "external_id": null,
          "status": ""
        },
        "return_address": {
          "street": "Example Street No:1",
          "city": "Maltepe",
          "city_code": "TR-34-108146",
          "state": "İstanbul",
          "state_code": "TR-34",
          "zip": "34857",
          "country": "Turkey",
          "country_code": "TR",
          "tax_id": "",
          "external_id": null,
          "status": ""
        }
      },
      "items": [
        {
          "id": "string",
          "name": "Product Name",
          "category": "gadget",
          "quantity": 1,
          "unit_price": 500.9,
          "origin": "TR",
          "hs_code": "",
          "sku": "",
          "weight": 0.5,
          "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
          }
        }
      ],
      "payment": {
        "currency": "TRY",
        "amount": 599.8,
        "type": "CODCash"
      },
      "customs": {},
      "extras": {
        "signature_confirmation": "",
        "just_document": false,
        "address_validation": false,
        "night_delivery": false,
        "saturday_delivery": false,
        "has_alcohol": false,
        "carbon_neutral": false
      },
      "document": {
        "labels": [
          {
            "id": "string",
            "process": "ready",
            "ready_at": "2019-08-24T14:15:22Z",
            "pdf": "https://access.shipink.io/document/label-7290012345678-normalA4.pdf?token=a0b1c2d3-0000-0000-0000-000011112222",
            "png": "http://example.com",
            "zpl": "http://example.com"
          }
        ],
        "customs_declaration": {
          "url": "http://example.com"
        },
        "sales_invoice": {
          "id": "inv_abc123",
          "no": "EFA2024001",
          "date": "2024-03-15T13:21:08Z",
          "url": "https://example.com/invoice.pdf"
        },
        "proforma": {}
      },
      "tracking": {
        "id": "track_abc123",
        "url": "https://kargo.aras.com.tr/track/507855220681824288",
        "estimated_delivery_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "status": "in_transit"
      },
      "rate": {
        "estimated_price": 45,
        "estimated_weight": 1,
        "estimated_at": "2019-08-24T14:15:22Z",
        "actual_price": 45,
        "actual_weight": 1,
        "heavy_load_fee": 150
      },
      "direction": "outgoing",
      "source": "api",
      "async": false,
      "create_invoice": false,
      "shipped_at": "2019-08-24T14:15:22Z",
      "delivered_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create a shipment

Creates a shipment for the specified order.

direction values:

  • outgoing — standard delivery
  • incoming — return shipment. A return code that is still pending 7 days after creation (no parcel handed in) is deleted automatically: the label is cancelled at the carrier and, on Shipink agreements, refunded.

Note: card_id is required when using a Shipink carrier account (Shipink agreements). You can retrieve your card IDs from the GET /cards endpoint or from the Shipink panel under payment settings.

Cash on delivery (COD)

To create a cash-on-delivery shipment, include the payment object in the request body with type set to one of:

  • CODCash — the carrier collects the amount in cash from the recipient.
  • CODCredit — the carrier collects the amount via credit card from the recipient.

Set amount to the value to collect from the recipient and optionally currency (defaults to the order currency). COD support depends on the selected carrier service — check the carrier_services[].payment_type.cod_cash / cod_credit flags on GET /carrier-accounts before creating the shipment, or pass payment_type to POST /rates to list only services that support COD. Omitting the payment object creates a standard shipment paid by the sender.

Carrier errors and timeouts

The request waits for the carrier and can take up to 45 seconds; set your client timeout above that. If the carrier does not answer in time the API returns 504 with meta.code SHIPMENT_CARRIER_REQUEST_TIMEOUT; if the carrier is unreachable or temporarily unavailable it returns 503 with CARRIER_UNAVAILABLE. On 503 and 504 no shipment is created and any charge is reverted, so the request can be retried. Invalid credentials on one of your own carrier accounts return 400 with CREDENTIALS_INVALID and name the carrier; update the account and retry.

POST
/shipments

Authorization

AuthorizationBearer <token>

Authenticate using the access_token obtained from POST /token.

Format: Authorization: Bearer {access_token}

In: header

Header Parameters

X-Language?string

Language code for the shipping label

Value in"tr" | "en"

Request Body

order_idstring
carrier_service_idstring
carrier_account_idstring
Formatuuid
warehouse_idstring
Formatuuid
direction?string

outgoing: standard delivery, incoming: return shipment

Value in"outgoing" | "incoming"
card_id?string

Required when using a Shipink carrier account (Shipink agreements). The ID of the payment card linked to your account.

Formatuuid
packages
payment?

Payment details for the shipment. Provide this object to create a cash-on-delivery (COD) shipment.

For a COD shipment set type to CODCash (collect cash) or CODCredit (collect via credit card at delivery) and set amount to the value to collect from the recipient. When omitted, the shipment defaults to Sender (shipping paid by the sender).

create_invoice?boolean
extras?

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://api.shipink.io/shipments" \  -H "Content-Type: application/json" \  -d '{    "direction": "outgoing",    "order_id": "Nc220IyHvpV_",    "carrier_service_id": "sendeo_standart",    "carrier_account_id": "efd4158f-75ca-4922-b8cc-c27e209db7e1",    "warehouse_id": "b4213a03-d4c3-41f8-8090-886e273de746",    "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "sales_invoice": {      "no": "EFA2024001",      "date": "2024-03-15T13:21:08Z",      "url": "https://example.com/invoice.pdf"    },    "packages": [      {        "dimension_unit": "cm",        "height": 10,        "length": 20,        "width": 15,        "weight": 1,        "weight_unit": "kg"      }    ]  }'
{
  "id": "17ebb574-f53f-43c2-bcf6-8984f7fc100b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "order_id": "Nc220IyHvpV_",
  "carrier": {
    "shipment_id": "507855220681824288",
    "tracking_url": "https://kargo.aras.com.tr/track/507855220681824288",
    "invoice_id": "",
    "waybill_id": "",
    "carrier_id": "aras",
    "carrier_service_id": "aras_standart",
    "carrier_account_id": "efd4158f-75ca-4922-b8cc-c27e209db7e1",
    "shipment_type": "outgoing",
    "language": "tr",
    "settings": {
      "system_account": true,
      "denominator": 0,
      "is_marketplace": true,
      "label_id_range": "string",
      "label_support": true,
      "return_support": true,
      "payment_type": {
        "sender": true,
        "recipient": true,
        "cod_cash": true,
        "cod_credit": true
      }
    }
  },
  "content": "",
  "language": "tr",
  "note": "",
  "packages": [
    {
      "weight": 1,
      "weight_unit": "kg",
      "length": 20,
      "width": 15,
      "height": 10,
      "dimension_unit": "cm"
    }
  ],
  "sender": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Ahmet Yılmaz",
    "tax_id": "",
    "tax_office": "",
    "company": "",
    "email": {
      "main": "user@example.com",
      "work": ""
    },
    "phone": {
      "main": "905321234567",
      "work": "",
      "cell": "",
      "code": ""
    },
    "address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    },
    "return_address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    }
  },
  "recipient": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Ahmet Yılmaz",
    "tax_id": "",
    "tax_office": "",
    "company": "",
    "email": {
      "main": "user@example.com",
      "work": ""
    },
    "phone": {
      "main": "905321234567",
      "work": "",
      "cell": "",
      "code": ""
    },
    "address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    },
    "return_address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    }
  },
  "items": [
    {
      "id": "string",
      "name": "Product Name",
      "category": "gadget",
      "quantity": 1,
      "unit_price": 500.9,
      "origin": "TR",
      "hs_code": "",
      "sku": "",
      "weight": 0.5,
      "dimensions": {
        "length": 0,
        "width": 0,
        "height": 0
      }
    }
  ],
  "payment": {
    "currency": "TRY",
    "amount": 599.8,
    "type": "CODCash"
  },
  "customs": {},
  "extras": {
    "signature_confirmation": "",
    "just_document": false,
    "address_validation": false,
    "night_delivery": false,
    "saturday_delivery": false,
    "has_alcohol": false,
    "carbon_neutral": false
  },
  "document": {
    "labels": [
      {
        "id": "string",
        "process": "ready",
        "ready_at": "2019-08-24T14:15:22Z",
        "pdf": "https://access.shipink.io/document/label-7290012345678-normalA4.pdf?token=a0b1c2d3-0000-0000-0000-000011112222",
        "png": "http://example.com",
        "zpl": "http://example.com"
      }
    ],
    "customs_declaration": {
      "url": "http://example.com"
    },
    "sales_invoice": {
      "id": "inv_abc123",
      "no": "EFA2024001",
      "date": "2024-03-15T13:21:08Z",
      "url": "https://example.com/invoice.pdf"
    },
    "proforma": {}
  },
  "tracking": {
    "id": "track_abc123",
    "url": "https://kargo.aras.com.tr/track/507855220681824288",
    "estimated_delivery_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "status": "in_transit"
  },
  "rate": {
    "estimated_price": 45,
    "estimated_weight": 1,
    "estimated_at": "2019-08-24T14:15:22Z",
    "actual_price": 45,
    "actual_weight": 1,
    "heavy_load_fee": 150
  },
  "direction": "outgoing",
  "source": "api",
  "async": false,
  "create_invoice": false,
  "shipped_at": "2019-08-24T14:15:22Z",
  "delivered_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}

{
  "success": false,
  "meta": {
    "status": 400,
    "code": "INVALID_INPUT",
    "message": "There is some problem with the data you submitted.",
    "details": [
      {
        "field": "name",
        "error": "cannot be blank"
      }
    ]
  }
}
{
  "success": true,
  "meta": {
    "status": 200,
    "code": "NOT_FOUND",
    "message": "orders successfully received",
    "total": 100,
    "details": [
      {
        "field": "name",
        "error": "cannot be blank"
      }
    ]
  }
}
{
  "success": true,
  "meta": {
    "status": 200,
    "code": "NOT_FOUND",
    "message": "orders successfully received",
    "total": 100,
    "details": [
      {
        "field": "name",
        "error": "cannot be blank"
      }
    ]
  }
}

Get a shipment

Returns the details of the specified shipment.

GET
/shipments/{shipment_id}

Authorization

AuthorizationBearer <token>

Authenticate using the access_token obtained from POST /token.

Format: Authorization: Bearer {access_token}

In: header

Path Parameters

shipment_idstring

Shipment ID

Formatuuid

Response Body

application/json

curl -X GET "https://api.shipink.io/shipments/17ebb574-f53f-43c2-bcf6-8984f7fc100b"
{
  "id": "17ebb574-f53f-43c2-bcf6-8984f7fc100b",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "order_id": "Nc220IyHvpV_",
  "carrier": {
    "shipment_id": "507855220681824288",
    "tracking_url": "https://kargo.aras.com.tr/track/507855220681824288",
    "invoice_id": "",
    "waybill_id": "",
    "carrier_id": "aras",
    "carrier_service_id": "aras_standart",
    "carrier_account_id": "efd4158f-75ca-4922-b8cc-c27e209db7e1",
    "shipment_type": "outgoing",
    "language": "tr",
    "settings": {
      "system_account": true,
      "denominator": 0,
      "is_marketplace": true,
      "label_id_range": "string",
      "label_support": true,
      "return_support": true,
      "payment_type": {
        "sender": true,
        "recipient": true,
        "cod_cash": true,
        "cod_credit": true
      }
    }
  },
  "content": "",
  "language": "tr",
  "note": "",
  "packages": [
    {
      "weight": 1,
      "weight_unit": "kg",
      "length": 20,
      "width": 15,
      "height": 10,
      "dimension_unit": "cm"
    }
  ],
  "sender": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Ahmet Yılmaz",
    "tax_id": "",
    "tax_office": "",
    "company": "",
    "email": {
      "main": "user@example.com",
      "work": ""
    },
    "phone": {
      "main": "905321234567",
      "work": "",
      "cell": "",
      "code": ""
    },
    "address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    },
    "return_address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    }
  },
  "recipient": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "Ahmet Yılmaz",
    "tax_id": "",
    "tax_office": "",
    "company": "",
    "email": {
      "main": "user@example.com",
      "work": ""
    },
    "phone": {
      "main": "905321234567",
      "work": "",
      "cell": "",
      "code": ""
    },
    "address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    },
    "return_address": {
      "street": "Example Street No:1",
      "city": "Maltepe",
      "city_code": "TR-34-108146",
      "state": "İstanbul",
      "state_code": "TR-34",
      "zip": "34857",
      "country": "Turkey",
      "country_code": "TR",
      "tax_id": "",
      "external_id": null,
      "status": ""
    }
  },
  "items": [
    {
      "id": "string",
      "name": "Product Name",
      "category": "gadget",
      "quantity": 1,
      "unit_price": 500.9,
      "origin": "TR",
      "hs_code": "",
      "sku": "",
      "weight": 0.5,
      "dimensions": {
        "length": 0,
        "width": 0,
        "height": 0
      }
    }
  ],
  "payment": {
    "currency": "TRY",
    "amount": 599.8,
    "type": "CODCash"
  },
  "customs": {},
  "extras": {
    "signature_confirmation": "",
    "just_document": false,
    "address_validation": false,
    "night_delivery": false,
    "saturday_delivery": false,
    "has_alcohol": false,
    "carbon_neutral": false
  },
  "document": {
    "labels": [
      {
        "id": "string",
        "process": "ready",
        "ready_at": "2019-08-24T14:15:22Z",
        "pdf": "https://access.shipink.io/document/label-7290012345678-normalA4.pdf?token=a0b1c2d3-0000-0000-0000-000011112222",
        "png": "http://example.com",
        "zpl": "http://example.com"
      }
    ],
    "customs_declaration": {
      "url": "http://example.com"
    },
    "sales_invoice": {
      "id": "inv_abc123",
      "no": "EFA2024001",
      "date": "2024-03-15T13:21:08Z",
      "url": "https://example.com/invoice.pdf"
    },
    "proforma": {}
  },
  "tracking": {
    "id": "track_abc123",
    "url": "https://kargo.aras.com.tr/track/507855220681824288",
    "estimated_delivery_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "status": "in_transit"
  },
  "rate": {
    "estimated_price": 45,
    "estimated_weight": 1,
    "estimated_at": "2019-08-24T14:15:22Z",
    "actual_price": 45,
    "actual_weight": 1,
    "heavy_load_fee": 150
  },
  "direction": "outgoing",
  "source": "api",
  "async": false,
  "create_invoice": false,
  "shipped_at": "2019-08-24T14:15:22Z",
  "delivered_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "deleted_at": "2019-08-24T14:15:22Z"
}
Empty

Delete a shipment

Deletes the specified shipment.

DELETE
/shipments/{shipment_id}

Authorization

AuthorizationBearer <token>

Authenticate using the access_token obtained from POST /token.

Format: Authorization: Bearer {access_token}

In: header

Path Parameters

shipment_idstring

Shipment ID

Formatuuid

Response Body

application/json

curl -X DELETE "https://api.shipink.io/shipments/17ebb574-f53f-43c2-bcf6-8984f7fc100b"
{
  "success": true,
  "meta": {
    "status": 200,
    "code": "NOT_FOUND",
    "message": "orders successfully received",
    "total": 100,
    "details": [
      {
        "field": "name",
        "error": "cannot be blank"
      }
    ]
  }
}

How is this guide?