Getting Started

The Ship&co API is a flexible solution that allows you to integrate functions such as shipping label creation and shipment tracking.
With it, you can easily support multiple domestic and international shipping companies into your existing systems and applications.
See how a typical Ship&co API request and response works in the diagram below: Diagram

Key Features

Multi-Carrier Support

Domestic Japan: Yamato Transport, Sagawa Express, Japan Post, Seino.
International: DHL, FedEx, UPS, Japan Post International, Pegasus Global Express.

Core Shipping Operations

Get shipping rates across multiple carriers.
Create shipping labels in formats compliant with each shipping company.
Automatically generate customs invoices for international shipments.
Retrieve tracking numbers and delivery status.

Account & User Management

Create and manage sub-users within your organization.
Add carrier accounts and configure shipping preferences.
Centralized management for multi-user environments.

Get Your API Token

To begin using the Ship&co API, you'll need to register for a Ship&co account and refer to the Authorization section.

How It Works

The Ship&co API follows REST principles with a straightforward authentication and request model:

Authentication: Add your Ship&co API token to the HTTP header (see Authorization section for details).
API Calls: Send HTTP requests (GET/POST) with JSON payloads to the appropriate endpoints.

Request Examples

Check our Postman collection for ready-to-use API requests per carrier.

Important Note

API parameters and response formats may vary depending on the selected carrier and service type.
Always refer to carrier-specific documentation when implementing your integration.
Feel free to contact us if you have any questions.

Authorization

The Ship&co API uses API keys to authenticate requests. Adding the API token to HTTP headers enables you to be authorized to use the API. Please follow these steps to obtain the API token:

Login to the Ship&co dashboard
Click "Settings" and go to the "Create your Ship&co API Token" section:

Once created and copied, add the token to your HTTP headers to authenticate API requests:

x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD

You can use Sub User API tokens to manage data according to each user individually. See Sub User for more details.

*Note that if you create a new token, the previous one will become invalid and its API calls will produce errors.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

API Call Limit

x-api-call-limitstring

The amount available/total amount per unit time.

x-api-call-resetstring

The timestamp when the amount available above resets to total.

Header's response example

1"X-Api-Call-Limit": "9/10"
2"X-Api-Call-Reset": "Fri Feb 14 2025 16:28:44 GMT+0900 (Japan Standard Time)"

Shipment

Create Shipment

You can input shipment information including the specified shipping address, parcel, product information, carrier information, and the shipping label based on the consignee's address.

Test Environment: Adding "test": true in setup enables you to create dummy labels free-of-charge. You will not need to add a credit card to your account for this, but the labels generated under test conditions are not valid and therefore cannot be used for shipment. Test labels are currently only available for UPS, DHL, Sagawa and Yamato. Sagawa and Yamato don't require carrier account registration either.
The Yamato Transport test environment is available only from Monday to Friday, 09:00 to 22:00 (Japan Time). It is not available on Saturdays, Sundays.

Note: The parameters required for label creation or rate requests can vary depending on the carrier. Domestic Japan carriers (Yamato, Sagawa, JapanPost - YuPack, YuPacket, YuMail, Seino) may require different settings than international carriers such as FedEx, DHL, UPS, Pegasus, or JapanPost International.

Request

POST https://api.shipandco.com/v1/shipments

to_addressobjectrequired

Recipient's address.
Note that province needs to be set as a code, not a full name (e.g. CA for California in USA) if the country has its codes.
*The maximum length of addresses varies depending on carrier and services (e.g. DHL accepts 45 characters in address1 and address2 to have 90 in total).

from_addressobjectrequired

Sender's address.

setupobjectrequired

Setup information.
For more details, see Carrier And Services.
You can find the most optimized service with List Rates.
*Adding "test": true enables you to create dummy labels free-of-charge.

parcelsarray

Parcel information. *For domestic shipping, do not use this parameter and use pack size and amount in setup instead. Parcel size can be set as the three of width, height, and depth (cm) or the carrier defined size of package. Parcel weight can be set as weight(grams). package accepts the following values.
FedEX:
"fedex_envelope", "fedex_pak", "fedex_box", "fedex_10kg_box", "fedex_25kg_box", "fedex_tube"
DHL:
"dhl_jumbo_doc", "dhl_jumbo_parcel", "dhl_document", "dhl_express_envelope", "dhl_jumbo_box", "dhl_jumbo_junior_box"

productsarray

Product information.

customsobject

Custom information. The following values are available for content_type. "GIFT", "NON_COMMERCIAL_DOCS", "SAMPLE", "MERCHANDISE", "PERSONAL", "RETURN", "REPAIR", "OTHER"
Intercoms can be specified in the following way. "duty_paid": true = "DDP", "duty_paid": false = "DDU"
"ioss_number": IOSS Number is now available for shipments from abroad to Europe up to 150€. More information about IOSS here.

➜ You can find sample requests on Postman.

Response

idstring

Shipment ID. Usable for GET.

delivery.carrierstring

Specified carrier name.

delivery.tracking_numbersarray

Shipment tracking numbers. If the return label is generated, these are multiple.

delivery.labelstring

Created label image information. If the return label is generated, this has multiple pages.

delivery.invoicestring

PDF commercial invoice for the shipment encoded in Base64 format. Only included for international shipments when supported.

delivery.carrier_invoicestring

Link to the carrier's invoice PDF. Only included for international shipments when supported.

delivery.warningsarray

Warning message shown if the carrier has a specific one. (e.g. Ineligible for DHL PLT. If you receive DHL PLT warning, refer to this page)

Request

1{
2  "setup": {
3    "carrier_id": "3hoFeaK12ere8484s",
4    "service": "yamato_regular",
5    "ref_number": "照会番号。。。",
6    "pack_amount": 1,
7    "shipment_date": "2025-01-18",
8    "cool_options": "frozen"
9  },
10  "from_address": {
11    "full_name": "テスト 名前",
12    "company": "テスト Inc.",
13    "email": "test@gmail.com",
14    "phone": "08044523652",
15    "country": "JP",
16    "zip": "5670001",
17    "province": "大阪府",
18    "address1": "茨木市安威",
19    "address2": "2丁目1番15号",
20    "extra": "ビル西"
21  },
22  "to_address": {
23    "full_name": "西中島 太郎",
24    "company": "一般会社",
25    "email": "abcd@gmail.com",
26    "phone": "08044512365",
27    "country": "JP",
28    "zip": "3420038",
29    "province": "埼玉県",
30    "address1": "吉川市吉川市美南3-25-1ｲｵﾝ吉川美南東街区",
31    "address2": "ビルABCD",
32    "extra": "ドア84"
33  },
34  "products": [
35    {
36      "name": "商品1",
37      "price": 5000,
38      "quantity": 1
39    },
40    {
41      "name": "商品2",
42      "price": 3000,
43      "quantity": 2
44    },
45    {
46      "name": "商品3",
47      "price": 3250,
48      "quantity": 2
49    },
50    {
51      "name": "商品4",
52      "price": 1000,
53      "quantity": 5
54    }
55  ]
56}

This request returns the following response.

1{
2  "id": "API-FMZZCG87OQ",
3  "state": "active",
4  "test": false,
5  "scope": "api",
6  "created_at": "2025-01-14T08:30:05.873Z",
7  "to_address": {
8    "full_name": "西中島 太郎",
9    "company": "一般会社",
10    "address1": "吉川市吉川市美南3-25-1ｲｵﾝ吉川美南東街区",
11    "address2": "ビルABCD",
12    "extra": "ドア84",
13    "province": "埼玉県",
14    "zip": "3420038",
15    "country": "JP",
16    "phone": "08044512365",
17    "email": "abcd@gmail.com"
18  },
19  "from_address": {
20    "full_name": "テスト 名前",
21    "company": "テスト Inc.",
22    "address1": "茨木市安威",
23    "address2": "2丁目1番15号",
24    "extra": "ビル西",
25    "province": "大阪府",
26    "zip": "5670001",
27    "country": "JP",
28    "phone": "08044523652",
29    "email": "test@gmail.com"
30  },
31  "products": [
32    {
33      "name": "商品1",
34      "quantity": 1,
35      "price": 5000
36    },
37    {
38      "name": "商品2",
39      "quantity": 2,
40      "price": 3000
41    },
42    {
43      "name": "商品3",
44      "quantity": 2,
45      "price": 3250
46    },
47    {
48      "name": "商品4",
49      "quantity": 5,
50      "price": 1000
51    }
52  ],
53  "setup": {
54    "insurance": 0,
55    "ref_number": "照会番号。。。",
56    "discount": 0,
57    "shipping_fee": 0,
58    "pack_amount": 1,
59    "cool_options": "frozen",
60    "care": {}
61  },
62  "delivery": {
63    "carrier": "yamato",
64    "method": "yamato_regular",
65    "tracking_numbers": ["438496228414"],
66    "label": "https://storage.googleapis.com/dev-shipandco/labels/202501/xxxx/yyyy.pdf"
67  }
68}

List Shipments

Get a list of created shipments.
Only shipments created within the last 2 months are returned. Shipments older than 2 months will not be retrieved.

Request

GET https://api.shipandco.com/v1/shipments

carrierstring

Specify type of the carrier given by List Carriers

scopestring

Specify the scope of shipments - made using the API only, or using both API and inside the App (default: api, possible values: api, all)

statestring

default active, possible values: active, void, any

Response

Array of created shipments.

Pagination

For pagination parameters refer to the Pagination section.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1{
2  "id": "API-O8APFNW9S8",
3  "state": "active",
4  "scope": "api",
5  "created_at": "2019-01-07T14:15:01.151Z",
6  "to_address": {
7    "full_name": "John Doe",
8    "company": "John Doe Inc.",
9    "country": "FR",
10    "email": "john@doe.io",
11    "phone": "0601234567",
12    "address1": "32 Rue de Rivoli",
13    "address2": "Batiment A 4eme etage",
14    "city": "Paris",
15    "zip": "75001"
16  },
17  "from_address": {
18    "full_name": "Yamada Taro",
19    "company": "World Company",
20    "address1": "OSAKAFU",
21    "country": "JP",
22    "email": "ytaro@worldcompany.com",
23    "phone": "08012341234",
24    "address2": "OTECHO",
25    "city": "IBARAKI SHI",
26    "province": "OSAKA",
27    "zip": "5670883"
28  },
29  "products": [
30    {
31      "name": "Basket ball",
32      "quantity": 2,
33      "price": 4850,
34      "hs_code": "HS9988",
35      "origin_country": "JP"
36    }
37  ],
38  "parcels": [
39    {
40      "weight": 200,
41      "amount": 1,
42      "width": 10,
43      "height": 10,
44      "depth": 10
45    }
46  ],
47  "customs": {
48    "duty_paid": false,
49    "content_type": "MERCHANDISE"
50  },
51  "setup": {
52    "currency": "JPY",
53    "insurance": 0,
54    "ref_number": "REF123456",
55    "delivery_note": "Please leave at the front door if unattended.",
56    "discount": 0,
57    "return_label": false,
58    "signature": false
59  },
60  "delivery": {
61    "carrier": "japanpost",
62    "method": "japanpost_ems",
63    "tracking_numbers": ["EN027977320JP"],
64    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/undefined.pdf"
65  }
66}

Get Shipment

Retrieve a shipment by the shipment ID.

Request

GET https://api.shipandco.com/v1/shipments/:id

Response

Only one shipment is displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1{
2  "id": "API-O8APFNW9S8",
3  "state": "active",
4  "scope": "api",
5  "created_at": "2019-01-07T14:15:01.151Z",
6  "to_address": {
7    "full_name": "John Doe",
8    "company": "John Doe Inc.",
9    "country": "FR",
10    "email": "john@doe.io",
11    "phone": "0601234567",
12    "address1": "32 Rue de Rivoli",
13    "address2": "Batiment A 4eme etage",
14    "city": "Paris",
15    "zip": "75001"
16  },
17  "from_address": {
18    "full_name": "Yamada Taro",
19    "company": "World Company",
20    "address1": "OSAKAFU",
21    "country": "JP",
22    "email": "ytaro@worldcompany.com",
23    "phone": "08012341234",
24    "address2": "OTECHO",
25    "city": "IBARAKI SHI",
26    "province": "OSAKA",
27    "zip": "5670883"
28  },
29  "products": [
30    {
31      "name": "Basket ball",
32      "quantity": 2,
33      "price": 4850,
34      "hs_code": "HS9988",
35      "origin_country": "JP"
36    }
37  ],
38  "parcels": [
39    {
40      "weight": 200,
41      "amount": 1,
42      "width": 10,
43      "height": 10,
44      "depth": 10
45    }
46  ],
47  "customs": {
48    "duty_paid": false,
49    "content_type": "MERCHANDISE"
50  },
51  "setup": {
52    "currency": "JPY",
53    "insurance": 0,
54    "ref_number": "REF123456",
55    "delivery_note": "Please leave at the front door if unattended.",
56    "discount": 0,
57    "return_label": false,
58    "signature": false
59  },
60  "delivery": {
61    "carrier": "japanpost",
62    "method": "japanpost_ems",
63    "tracking_numbers": ["EN027977320JP"],
64    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/undefined.pdf"
65  }
66}

Delete Shipment

Delete a shipment by the shipment ID.

Request

DELETE https://api.shipandco.com/v1/shipments/:id

Response

The resulting message is displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1"Shipment API-O8APFNW9S8 deleted."

Rates

List Rates

The RATES API allows you to retrieve shipping rates based on the provided shipping information. The rates for each specified carrier are displayed in a list. Note that the RATES API is designed to be used in conjunction with the shipment API. Using the RATES API in isolation may result in the disabling of your access token.

Request

POST https://api.shipandco.com/v1/rates

The request parameters are similar to those used in the shipment creation API, with the service parameter excluded. For more details, see the Create Shipment documentation.

Note: The parameters required for label creation or rate requests can vary depending on the carrier. Domestic Japan carriers (Yamato, Sagawa, JapanPost - YuPack, YuPacket, YuMail, Seino) may require different settings than international carriers such as FedEx, DHL, UPS, Pegasus, or JapanPost International.

➜ You can find sample requests on Postman.

Response

An array of rates for each service is returned. For more details, see Carrier And Services.

Carrier Details

• FedEx, DHL, UPS, Pegasus: Returns contract rates in the response.
• Japan Post International: Returns standard rates.
• Sagawa Express, Yamato Transport, Yu-Pack: Returns standard rates. These rates are only for regular services (without options like fresh or frozen shipping).

To retrieve freight rates for UPS freight services (ups_worldwide_express_freight, ups_worldwide_express_freight_mid_day), you must specify a parcel with either:
• A weight > 70 kgs (or 150 lbs), OR
• One of the depth, width, height dimensions > 154 cm (or 60 inches)

Error

When errors occur for specific carriers, the response includes both successful rates and an errors array containing details about failed carriers. Inside the array, each error object includes the carrier name and the corresponding error message, see the following example:

1{
2  "rates": [
3    {
4      "carrier_id": "aZSzwKJDGP5KfdRid",
5      "carrier": "fedex",
6      "service": "fedex_international_first",
7      "currency": "JPY",
8      "price": 31235,
9      "surcharges": []
10    }
11  ],
12  "errors": [
13    {
14      "carrier": "ups",
15      "message": "Invalid destination address"
16    },
17    {
18      "carrier": "japanpost", 
19      "message": "Service not available for this destination"
20    }
21  ]
22}

Request

1{
2  "setup": {
3    "currency": "JPY",
4    "ref_number": "123-REF-3456",
5    "signature": false
6  },
7  "to_address": {
8    "full_name": "John Doe",
9    "phone": "09000000",
10    "country": "FR",
11    "zip": "75002",
12    "city": "Paris",
13    "address1": "12 Rue du 2 juillet"
14  },
15  "from_address": {
16    "full_name": "Yamada Taro",
17    "company": "World Company",
18    "email": "ytaro@worldcompany.com",
19    "phone": "080000000",
20    "country": "JP",
21    "zip": "6050012",
22    "province": "KYOTO",
23    "city": "KYOTO",
24    "address1": "HIGASHIYAMA KU",
25    "address2": "SAIKAISHICHO"
26  },
27  "products": [
28    {
29      "name": "T-Shirt",
30      "quantity": 2,
31      "price": 25000,
32      "origin_country": "JP"
33    }
34  ],
35  "parcels": [
36    {
37      "weight": 2000,
38      "amount": 1,
39      "width": 10,
40      "height": 10,
41      "depth": 10
42    }
43  ],
44  "customs": {
45    "content_type": "MERCHANDISE"
46  }
47}

This request returns the following response.

1[
2  {
3    "carrier_id": "nznqM23wD3apjEJF6",
4    "carrier": "dhl",
5    "service": "dhl_express_0900",
6    "currency": "JPY",
7    "price": 10129,
8    "surcharges": [
9      {
10        "type": "9:00 PREMIUM",
11        "price": 5500
12      }
13    ]
14  },
15  {
16    "carrier_id": "nznqM23wD3apjEJF6",
17    "carrier": "dhl",
18    "service": "dhl_express_worldwide",
19    "currency": "JPY",
20    "price": 3021,
21    "surcharges": []
22  },
23  {
24    "carrier_id": "eMYDqTqiaR4Bdf4wW",
25    "carrier": "fedex",
26    "service": "fedex_international_first",
27    "currency": "JPY",
28    "price": 54954,
29    "surcharges": [
30      {
31        "type": "Demand Surcharge",
32        "price": 360
33      }
34    ]
35  },
36  {
37    "carrier_id": "eMYDqTqiaR4Bdf4wW",
38    "carrier": "fedex",
39    "service": "fedex_international_priority_express",
40    "currency": "JPY",
41    "price": 4116,
42    "surcharges": [
43      {
44        "type": "Demand Surcharge",
45        "price": 360
46      }
47    ]
48  },
49  {
50    "carrier_id": "FPTThBHJhDTA4CzPv",
51    "carrier": "japanpost",
52    "service": "japanpost_ems",
53    "currency": "JPY",
54    "price": 6700,
55    "surcharges": []
56  },
57  {
58    "carrier_id": "FPTThBHJhDTA4CzPv",
59    "carrier": "japanpost",
60    "service": "japanpost_smallpacket_air",
61    "currency": "JPY",
62    "price": 3930,
63    "surcharges": []
64  }
65]

Negotiated Rates

With Ship&co API, users can upload and delete negotiated rates for Japan domestic carriers, including Yamato Transport, Sagawa Express, and JapanPost YuPack. This allows merchants who have pre-negotiated rates with these carriers to input and manage their custom shipping rates. If no negotiated rates are uploaded, calling the rates API for these carriers will return public (non-discounted) rates.

Upload Negotiated Rates

Upload negotiated rates for domestic carriers.

Request

POST https://api.shipandco.com/v1/carriers/:id/rates

ratesarrayrequired

Response

The resulting message is displayed.

Carrier-Specific Region Naming Conventions

Each carrier uses different region names when setting negotiated rates. The following lists the correct 地方 (region names) for each carrier:

YuPack (JapanPost): 北海道, 東北, 関東, 信越, 北陸, 東海, 近畿, 中国, 四国, 九州, 沖縄
Sagawa Express: 北海道, 北東北, 南東北, 関東, 信越, 東海, 北陸, 関西, 中国, 四国, 北九州, 南九州, 沖縄
Yamato Transport: 北海道, 北東北, 南東北, 関東, 信越, 北陸, 中部, 関西, 中国, 四国, 九州, 沖縄

Ensure that the correct region names are used for each carrier when uploading rates. Important notes:

Rates must be uploaded using valid region names as per the carrier's specifications.
Frozen and Chilled Services rates support will be introduced later.

Request Upload Negotiated Rates

1[
2  {
3      "from": "北海道",
4      "size": 60,
5      "price": {
6          "南九州": "1,700",
7          "北九州": "1,700",
8          "四国": "1,600",
9          "関西": "1,500",
10          "中部": "1,400",
11          "北陸": "1,200",
12          "信越": "1,200",
13          "関東": "1,100",
14          "南東北": "1,100",
15          "北東北": "1,000",
16          "北海道": "700"
17      }
18  },
19  {
20      "from": "関東",
21      "size": 260,
22      "price": {
23          "南九州": "9,850",
24          "北九州": "9,800",
25          "四国": "8,800",
26          "関西": "8,000",
27          "中部": "8,000",
28          "北陸": "7,150",
29          "信越": "7,150",
30          "関東": "7,150",
31          "南東北": "7,150",
32          "北東北": "7,400",
33          "北海道": "9,950"
34      }
35    ]
36

Delete Negotiated Rates

Remove previously uploaded negotiated rates.

Request

DELETE https://api.shipandco.com/v1/carriers/:id/rates

Response

The resulting message is displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

Carrier

Register Carrier

Request

POST https://api.shipandco.com/v1/carriers

typestring

Type of carrier you want to add. Possible values are: japanpost, ups, fedex, dhl, sagawa, yamato, yuupack, yuupacket, yuumail, pegasus, seino.

credentialsobject

Credentials required for using carrier systems. The parameters inside this are different from each other. See the following for the details.

settingsobject

Settings specific to each carrier. The parameters inside this are different from each other. See the following for the details.

➜ You can find sample requests on Postman.

Credentials parameter by carrier

DHL

In order to obtain your DHL Site ID and Password, our DHL support page will guide you to quickly get them from DHL.

site_idstringrequired

passwordstringrequired

account_numberstringrequired

import_acc_numberstring

address.countrystringrequired

address.zipstringrequired

address.address1String

address.address2String

address.cityString

address.companyString

address.emailString

address.full_nameString

address.phoneString

UPS

access_keystringrequired

account_numberstringrequired

passwordstringrequired

user_namestringrequired

FedEx

account_numberstringrequired

address.address1stringrequired

address.address2stringrequired

address.citystringrequired

address.companystringrequired

address.countrystringrequired

address.emailstringrequired

address.full_namestringrequired

address.phonestringrequired

address.zipstringrequired

invoice_2faobjectrequired

Required when registering a FedEx account via the API. This object provides the invoice details used for 2FA (invoice number verification). In addition to the standard FedEx account credentials, include the latest invoice details.

Japan Post International

customer_numbersarray

Array, minLength: 4, maxLength: 4, required (eg: ['000000000','000000000','000000000','000000000'])

Sagawa

account_numberstringrequired

keystringrequired

passwordstringrequired

In order to get the key and password from Sagawa, a request must be submitted through the "carrier options" function on the Ship&co dashboard. After approval, Sagawa will notify Ship&co of your information for account activation, then you will receive an email for this from Ship&co. This process will take about 5 to 8 business days.

Japan Post Domestic (Yuupack)

user_idstringrequired

In order to obtain your user ID from Japan Post, this form must be filled and submitted to Japan Post. Japan Post will then check, approve and issue a code, and email it to you for account activation. This will take about 5 to 8 business days. PLEASE NOTE: you need to have a post-payment agreement with Japan Post in order to apply for this.

Japan Post Domestic (Yuupacket)

The same as above.

Japan Post Domestic (Yuumail)

The same as above.

Yamato

keystringrequired

freight_numberstring

default: '01'

Yamato International

user_keystringrequired

freight_numberstring

default: '01'

Pegasus

user_idstringrequired

passwordstringrequired

Seino

For Seino carrier setup, refer to our support page for detailed instructions.

access_keystringrequired

niokurininstringrequired

Settings by carrier

DHL

label.hide_accountboolean

Whether to print account information on labels or not.

label.extra_pageboolean

Whether to create a page for archiving or not.

print.sizestringrequired

Label size to use. The valid values: "PDF_4X6", "PDF_4X8", "ZPL_4X6"

UPS

print.sizestringrequired

Label size to use. The valid values: "PDF_4X6", "ZPL_4X6"

FedEx

print.sizestringrequired

Label size to use. The valid values: "PDF_4X6", "PDF_4X8", "PDF_4X9", "ZPL_4X6", "ZPL_4X8"

Japan Post International

print.sizestringrequired

Label size to use. The valid values: "PDF_A4"

Sagawa

print.sizestringrequired

Label size to use. The valid values: "PDF_A5", "PDF_4.2X8.3_BLUE", "PDF_4.2X8.3_GREEN"

Japan Post Domestic (Yuupack)

print.sizestringrequired

Label size to use. The valid values: "PDF_A5", "PDF_YU_THERMAL"

Japan Post Domestic (Yuupacket)

print.sizestringrequired

Label size to use. The valid values: "PDF_A5", "PDF_YU_THERMAL"

Japan Post Domestic (Yuumail)

print.sizestringrequired

Label size to use. The valid values: "PDF_A5", "PDF_YU_THERMAL"

Yamato

print.sizestringrequired

Label size to use. The valid values: "PDF_A4", "PDF_A5", "PDF_A4_BW", "PDF_A5_BW", "PDF_4.5X7.8"

print.size_fallbackstring

Required when print.size is set to thermal type (PDF_4.5X7.8). Optional otherwise. Used as a fallback when the specified shipping service doesn't support thermal type during label generation. Valid values: "PDF_A4", "PDF_A5", "PDF_A4_BW", "PDF_A5_BW"

scheduled_delivery_email.enabledboolean

When shipping a package, set up Yamato to automatically send an email to the delivery address with the estimated delivery date and time.

scheduled_delivery_email.messagestring

Required when scheduled_delivery_email.enabled is set to true. Set a custom message to be inserted into the email, up to 74 characters.

label.delivery_dateboolean

A setting that automatically prints the earliest possible delivery date on the label when issuing a label without specifying a delivery date (setup.date).

Response

Registered carrier information with its ID

Request

1{
2  "type": "yamato",
3  "credentials": {
4    "key": "your_key",
5    "freight_number": "your_freight_number"
6  },
7  "settings": {
8    "print": {
9      "size": "PDF_A4"
10    }
11  }
12}

This request returns the following response.

1{
2  "id": "a5PZ3428ku784W7gc",
3  "type": "yamato",
4  "state": "active",
5  "created_at": "2025-03-10T06:49:21.730Z",
6  "updated_at": "2025-03-10T06:49:21.730Z",
7  "credentials": {
8    "key": "*****",
9    "freight_number": "*****"
10  },
11  "settings": {
12    "print": {
13      "size": "PDF_A4"
14    }
15  }
16}

List Carriers

Retrieves a list of registered carriers.

Request

GET https://api.shipandco.com/v1/carriers

Response

Array of registered carriers information displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1[
2  {
3    "id": "GZDZQNo7zyxr4sbXc",
4    "type": "yuupacket",
5    "state": "active",
6    "created_at": "2019-01-07T14:24:13.045Z",
7    "updated_at": "2019-01-07T14:24:13.045Z",
8    "credentials": {
9      "user_id": "***********"
10    }
11  },
12  {
13    "id": "FbqDPqcBL6AL7PwAo",
14    "type": "yuupack",
15    "state": "active",
16    "created_at": "2019-01-07T14:24:13.042Z",
17    "updated_at": "2019-01-07T14:24:13.042Z",
18    "credentials": {
19      "user_id": "***********"
20    }
21  },
22  {
23    "id": "7iuaQaEp8fasKCzgD",
24    "type": "yamato",
25    "state": "active",
26    "created_at": "2019-01-07T14:06:13.197Z",
27    "updated_at": "2019-01-07T14:06:13.197Z",
28    "credentials": {
29      "key": "*********************************************************",
30      "freight_number": "**"
31    }
32  },
33  {
34    "id": "tbEuFScyfSQMx7bN8",
35    "type": "sagawa",
36    "state": "active",
37    "created_at": "2019-01-07T14:06:39.627Z",
38    "updated_at": "2019-01-07T14:08:45.817Z",
39    "credentials": {
40      "key": "********",
41      "password": "************************",
42      "account_number": "***********",
43      "account_key_number": ""
44    }
45  },
46  {
47    "id": "CFjQRubN5jhhT5hTb",
48    "type": "japanpost",
49    "state": "active",
50    "created_at": "2018-09-24T15:33:58.145Z",
51    "updated_at": "2018-09-24T15:33:58.145Z",
52    "credentials": {
53      "customer_numbers": "****"
54    }
55  }
56]

Update Carrier

Update a carrier by carrier ID.

Request

PUT https://api.shipandco.com/v1/carriers/:id

settingsobject

Credentials required for using carrier systems. The parameters inside this are different from each other. See the following for the details.

Response

Updated carrier information with its ID

Request

1{
2  "settings": {
3    "print": {
4      "size": "PDF_4.2X8.3_BLUE"
5    }
6  }
7}

This request returns the following response.

1{
2  "id": "g3buDjYMCXaj6zNCv",
3  "type": "sagawa",
4  "state": "active",
5  "created_at": "2019-02-25T11:58:57.852Z",
6  "updated_at": "2019-02-25T11:58:57.852Z",
7  "credentials": {
8    "account_number": "*********",
9    "key": "*********",
10    "password": "*********"
11  }
12}

Delete Carrier

Delete a carrier by carrier ID.

Request

DELETE https://api.shipandco.com/v1/carriers/:id

Response

The resulting message is displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1"Carrier GZDZQNo7zyxr4sbXc deleted."

Tracking

Get Tracking

Obtain tracking information with a carrier and its relevant tracking number. Tracking is supported for the following carriers:
• Japanpost International
• Japanpost Domestic (Yuupack, Yupacket)
• Yamato Transport
• Sagawa Express
• UPS
• DHL

Request

GET https://api.shipandco.com/v1/tracking/:carrier/:trackingNumber

Response

Carrier's tracking information displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1{
2  "requested_at": "2019-05-22T14:52:35.155Z",
3  "carrier": "japanpost",
4  "tracking_number": "RN004792035JP",
5  "service": "Registered Mail / Insured Mail",
6  "from_address": {},
7  "to_address": {},
8  "current_status": {
9    "date": "2019-05-20T17:30:00.000Z",
10    "status": "Arrival at outward office of exchange",
11    "details": "",
12    "location": "OSAKA"
13  },
14  "history": [
15    {
16      "date": "2019-05-20T07:45:00.000Z",
17      "status": "Posting/Collection",
18      "details": "",
19      "location": "OSAKA"
20    },
21    {
22      "date": "2019-05-20T17:30:00.000Z",
23      "status": "Arrival at outward office of exchange",
24      "details": "",
25      "location": "OSAKA"
26    }
27  ]
28}

Shipping Address

Register Shipping Address

Request

POST https://api.shipandco.com/v1/addresses

Shipping address information to register. See Create Shipment for more details.

Response

Registered shipping address information with its ID.

Request

1{
2  "full_name": "Ship Co",
3  "company": "Ship&Co",
4  "email": "shipco@shipandco.com",
5  "phone": "0312345678",
6  "country": "JP",
7  "address1": "chukyo-ku",
8  "address2": "Building A",
9  "extra": "Suite 123",
10  "province": "Kyoto-fu",
11  "zip": "123-4567",
12  "city": "Kyoto-shi"
13}

This request returns the following response.

1{
2  "id": "kr54qe8YPdc5HZSBu",
3  "created_at": "2019-01-12T09:04:43.619Z",
4  "updated_at": "2019-01-12T09:04:43.619Z",
5  "address": {
6    "full_name": "Ship Co",
7    "company": "Ship&Co",
8    "address1": "chukyo-ku",
9    "address2": "Building A",
10    "extra": "Suite 123",
11    "city": "Kyoto-shi",
12    "province": "Kyoto-fu",
13    "zip": "123-4567",
14    "country": "JP",
15    "phone": "0312345678",
16    "email": "shipco@shipandco.com"
17  }
18}

List Shipping Addresses

To retrieve a list of registered shipping addresses.

Request

GET https://api.shipandco.com/v1/addresses

Response

Array of registered shipping addresses information.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1[
2  {
3    "id": "dC32vpNEja8W7WNwR",
4    "created_at": "2019-01-12T08:32:55.411Z",
5    "updated_at": "2019-01-12T08:32:55.411Z",
6    "address": {
7      "full_name": "John Doe",
8      "company": "John Doe Inc.",
9      "country": "FR",
10      "email": "john@doe.io",
11      "phone": "0601234567",
12      "address1": "32 Rue de Rivoli",
13      "address2": "Batiment A 4eme etage",
14      "city": "Paris",
15      "zip": "75001"
16    }
17  },
18  {
19    "id": "kr54qe8YPdc5HZSBu",
20    "created_at": "2019-01-12T09:04:43.619Z",
21    "updated_at": "2019-01-12T09:04:43.619Z",
22    "address": {
23      "full_name": "Ship Co",
24      "company": "Ship&Co",
25      "address1": "chukyo-ku",
26      "address2": "Building A",
27      "extra": "Suite 123",
28      "city": "Kyoto-shi",
29      "province": "Kyoto-fu",
30      "zip": "123-4567",
31      "country": "JP",
32      "phone": "0312345678",
33      "email": "shipco@shipandco.com"
34    }
35  }
36]

Warehouse

Register Warehouse

Warehouse information to register

Request

POST https://api.shipandco.com/v1/warehouses

Response

Registered warehouse information with its ID

Request

1{
2  "full_name": "Taro Yamada",
3  "full_name_kanji": "山田太郎",
4  "company": "ACME",
5  "company_kanji": "株式会社ACME",
6  "email": "taro.yamada@example.com",
7  "phone": "090-1234-5678",
8  "country": "JP",
9  "address1": "HIGASHIYAMA KU",
10  "address2": "SAIKAISHICHO",
11  "province": "KYOTO",
12  "address1_kanji": "京都市東山区",
13  "address2_kanji": "西海子町",
14  "extra_kanji": "神宮道",
15  "province_kanji": "京都府",
16  "zip": "604-0012",
17  "city": "KYOTO SHI"
18}

This request returns the following response.

1{
2  "id": "cki5wYEHddBZuEtPv",
3  "created_at": "2019-01-31T07:34:25.071Z",
4  "updated_at": "2019-01-31T07:34:25.071Z",
5  "address": {
6    "full_name": "Taro Yamada",
7    "company": "ACME",
8    "address1": "HIGASHIYAMA KU",
9    "address2": "SAIKAISHICHO",
10    "city": "KYOTO SHI",
11    "province": "KYOTO",
12    "zip": "604-0012",
13    "country": "JP",
14    "phone": "090-1234-5678",
15    "email": "taro.yamada@example.com",
16    "full_name_kanji": "山田太郎",
17    "company_kanji": "株式会社ACME",
18    "address1_kanji": "京都市東山区",
19    "address2_kanji": "西海子町",
20    "extra_kanji": "神宮道",
21    "province_kanji": "京都府"
22  }
23}

List Warehouses

Get a list of registered warehouse information.

Request

GET https://api.shipandco.com/v1/warehouses

Response

Array of registered warehouse information.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1[
2  {
3    "id": "cki5wYEHddBZuEtPv",
4    "created_at": "2019-01-31T07:34:25.071Z",
5    "updated_at": "2019-01-31T07:34:25.071Z",
6    "address": {
7      "full_name": "Taro Yamada",
8      "company": "ACME",
9      "address1": "HIGASHIYAMA KU",
10      "address2": "SAIKAISHICHO",
11      "city": "KYOTO SHI",
12      "province": "KYOTO",
13      "zip": "604-0012",
14      "country": "JP",
15      "phone": "090-1234-5678",
16      "email": "taro.yamada@example.com",
17      "full_name_kanji": "山田太郎",
18      "company_kanji": "株式会社ACME",
19      "address1_kanji": "京都市東山区",
20      "address2_kanji": "西海子町",
21      "extra_kanji": "神宮道",
22      "province_kanji": "京都府"
23    }
24  },
25  {
26    "id": "phuAH6qFvoxdASoCr",
27    "created_at": "2019-01-31T07:37:46.332Z",
28    "updated_at": "2019-01-31T07:37:46.332Z",
29    "address": {
30      "full_name": "John Doe",
31      "company": "John Doe Inc.",
32      "country": "FR",
33      "email": "john@doe.io",
34      "phone": "0601234567",
35      "address1": "32 Rue de Rivoli",
36      "address2": "Batiment A 4eme etage",
37      "city": "Paris",
38      "zip": "75001"
39    }
40  }
41]

Files

Upload File

This endpoint is used to upload files for Ship&Co settings. It is currently required for DHL's paperless invoicing.

Request

POST https://api.shipandco.com/v1/files

filestringrequired

The file size should be 1MB or less. PNG or JPEG encoded in Base64

typestringrequired

The types of files that can be uploaded are as follows:

"signature": Image file for electronic signature
"logo": Image file for logo

Response

filestring

Encoded Base64 image

idstring

Image ID

typestring

Image type

Request

1{
2  "type": "logo",
3  "file": "iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAMAAAA/pq9xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyVpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDYuMC1jMDA2IDc5LjE2NDY0OCwgMjAyMS8wMS8xMi0xNTo1MjoyOSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIDIyLjIgKE1hY2ludG9zaCkiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6MjMxNTMyODc2ODU2MTFFQkE2NDFFODc1MTVGQUYyMzUiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6MjMxNTMyODg2ODU2MTFFQkE2NDFFODc1MTVGQUYyMzUiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDoyMzE1MzI4NTY4NTYxMUVCQTY0MUU4NzUxNUZBRjIzNSIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDoyMzE1MzI4NjY4NTYxMUVCQTY0MUU4NzUxNUZBRjIzNSIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PhUt+OUAAAAMUExURf38/C4pKv9WHreppVucDhcAAAHiSURBVHjatFfZtoQgDCvk//95pDvrwxxgPApcbUhaopfo2IBav4OetS94aw3mFUTNDQ9JMI/2e8oCz/RCJ9QbDA8OIfKiunKujcg9EHwtMEK5i3J1iYiw9WZx1aH1f3jCI8LeZDJiuFycdrzBSIm/VcCoGxRcNK56aHiPgWu1dYTAY4x/w2PuHyCAUprVtA7fzRcZfKd2IFuSd+Up7tqTdVldoKKtRWxnvsg0d7lxiAJHkaC2DkHayxZxOhA7l4SibMnPolNxbrvdwivm5ZBEdCYBAlvDAiTjudvOnw6mhVPgyIkJDJbXvAeJ7GPUSwTRR7mH4hwsumFZfk9MtF7XOVEQT8HIRCjO+g9M0us26xUogTEnnmcoannDZHJE54K0+JmJE42UbJkM75Bh6BmgzCHXt0Zr8MecYIGiQmMAyTnpJUI5V1eXiXHD2yafNuO40nKsLnSeeN7xWIAUNSreMpGbko0mvudqHhHcnGZbQQJh75L73McK9V3dJjBvT/npzW1l5St7GizZPAWiWTLKR//2+Cvw3tfcQQSjAbc8/slVBuRTVjrk9ggNpXeBzpKnQNCbYaDa0Xk7kCcNFIQjN8uhPuQkHNqQKeFlbOyY9KQkCkw0kxEwxDTnI12+r+EnwAA0EQvTI8JTUwAAAABJRU5ErkJggg=="
4}

This request returns the following response.

1{
2  "id": "phuAH6qFvoxdASoCr",
3  "type": "logo",
4  "file": "iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAMAAAA/pq9xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyVpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDYuMC1jMDA2IDc5LjE2NDY0OCwgMjAyMS8wMS8xMi0xNTo1MjoyOSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIDIyLjIgKE1hY2ludG9zaCkiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6MjMxNTMyODc2ODU2MTFFQkE2NDFFODc1MTVGQUYyMzUiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6MjMxNTMyODg2ODU2MTFFQkE2NDFFODc1MTVGQUYyMzUiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDoyMzE1MzI4NTY4NTYxMUVCQTY0MUU4NzUxNUZBRjIzNSIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDoyMzE1MzI4NjY4NTYxMUVCQTY0MUU4NzUxNUZBRjIzNSIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PhUt+OUAAAAMUExURf38/C4pKv9WHreppVucDhcAAAHiSURBVHjatFfZtoQgDCvk//95pDvrwxxgPApcbUhaopfo2IBav4OetS94aw3mFUTNDQ9JMI/2e8oCz/RCJ9QbDA8OIfKiunKujcg9EHwtMEK5i3J1iYiw9WZx1aH1f3jCI8LeZDJiuFycdrzBSIm/VcCoGxRcNK56aHiPgWu1dYTAY4x/w2PuHyCAUprVtA7fzRcZfKd2IFuSd+Up7tqTdVldoKKtRWxnvsg0d7lxiAJHkaC2DkHayxZxOhA7l4SibMnPolNxbrvdwivm5ZBEdCYBAlvDAiTjudvOnw6mhVPgyIkJDJbXvAeJ7GPUSwTRR7mH4hwsumFZfk9MtF7XOVEQT8HIRCjO+g9M0us26xUogTEnnmcoannDZHJE54K0+JmJE42UbJkM75Bh6BmgzCHXt0Zr8MecYIGiQmMAyTnpJUI5V1eXiXHD2yafNuO40nKsLnSeeN7xWIAUNSreMpGbko0mvudqHhHcnGZbQQJh75L73McK9V3dJjBvT/npzW1l5St7GizZPAWiWTLKR//2+Cvw3tfcQQSjAbc8/slVBuRTVjrk9ggNpXeBzpKnQNCbYaDa0Xk7kCcNFIQjN8uhPuQkHNqQKeFlbOyY9KQkCkw0kxEwxDTnI12+r+EnwAA0EQvTI8JTUwAAAABJRU5ErkJggg=="
5}

List Files

Get a list of your uploaded files.

Request

GET https://api.shipandco.com/v1/files

Response

Array of uploaded files

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1[
2  {
3    "id": "cki5wYEHddBZuEtPv",
4    "type": "signature",
5    "file": "iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAMAAAA/pq9xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyVpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+"
6  },
7  {
8    "id": "phuAH6qFvoxdASoCr",
9    "type": "logo",
10    "file": "iVBORw0KGgoAAAANSUhEUgAAAGQAAAAoCAMAAAA/pq9xAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyVpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+"
11  }
12]

Sub User

Sub users under a regular Ship&co account can have their own individual tokens to call APIs. Data is segmented according to each sub user account. Do note that sub user APIs can only accept regular tokens (which means sub users cannot call sub user APIs themselves).

Register Sub User

Request

POST https://api.shipandco.com/v1/sub-users

emailstringrequired

Required. Key of sub users

api_tokenboolean

Request a token or not.

contactobject

first_name, last_name, full_name (optional), company

➜ You can find sample requests on Postman.

Response

Registered sub user information with its ID and API token. Generated API token can be used for other APIs. See Authorization.

Request

1{
2  "contact": {
3    "first_name": "John",
4    "last_name": "Doe",
5    "company": "ACME"
6  },
7  "email": "email@test.com",
8  "api_token": true
9}

This request returns the following response.

1{
2  "id": "f1f97cfa813c828a73528989da671a81",
3  "created_at": "2019-02-25T11:12:14.021Z",
4  "email": "email@test.com",
5  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
6  "first_name": "John",
7  "last_name": "Doe",
8  "company": "ACME"
9}

List Sub Users

Obtain a list of registered sub user information.

Request

GET https://api.shipandco.com/v1/sub-users

Array of registered sub user information.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1[
2  {
3    "id": "f1f97cfa813c828a73528989da671a81",
4    "created_at": "2019-02-25T11:12:14.021Z",
5    "email": "email@test.com",
6    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
7    "first_name": "John",
8    "last_name": "Doe",
9    "company": "ACME"
10  },
11  {
12    "id": "929ab359ada3fa5c7bf53bff7ffcbe58",
13    "created_at": "2019-02-26T11:08:13.749Z",
14    "email": "email2@test.com",
15    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzam9qand4ejlQdWZzRXp4IiwiaWF0IjoxNTUxMTc5MjkzfQ.RLb2jWjwo9FZwP3MSyyDYkbQZMTtmjMvTYql-dfgk1o",
16    "first_name": "John 2",
17    "last_name": "Doe 2",
18    "company": "ACME 2"
19  }
20]

Get Sub User

Retrieve a sub user by the sub user ID.

Request

GET https://api.shipandco.com/v1/sub-users/:id

Response

Only one sub user is displayed per command.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1{
2  "id": "f1f97cfa813c828a73528989da671a81",
3  "created_at": "2019-02-25T11:12:14.021Z",
4  "email": "email@test.com",
5  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
6  "first_name": "John",
7  "last_name": "Doe",
8  "company": "ACME"
9}

Refresh Sub User

Recreate API token of a sub user.

Request

POST https://api.shipandco.com/v1/sub-users/:id

Response

API token recreated for the requested sub user.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1{
2  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMTc5OTgyfQ.sQChZ4DjIPyDbgOmJ2-jUgMe_xw9d52-TBGizg9lPjo"
3}

Delete Sub User

Delete a sub user by the carrier ID.

Request

DELETE https://api.shipandco.com/v1/sub-users/:id

Response

The resulting message is displayed.

Request headers

1{
2  "x-access-token": "YOUR_API_TOKEN_FROM_DASHBOARD",
3  "Content-Type": "application/json"
4}

This request returns the following response.

1"Child user f1f97cfa813c828a73528989da671a81:email@test.com deleted."

Common Definition

Carrier And Services

Carrier	Value	Service Values	Intl
Japan Post International	japanpost	`japanpost_ems`, `japanpost_ems_document`, `japanpost_epacket_light`, `japanpost_smallpacket_registered_sal`, `japanpost_smallpacket_registered_air`, `japanpost_smallpacket_registered_sea`, `japanpost_smallpacket_sal`, `japanpost_smallpacket_air`, `japanpost_smallpacket_sea`, `japanpost_parcel_sal`, `japanpost_parcel_air`, `japanpost_parcel_sea`, `japanpost_printed_matter_sal`, `japanpost_printed_matter_air`, `japanpost_printed_matter_sea`, `japanpost_printed_matter_registered_sal`, `japanpost_printed_matter_registered_air`, `japanpost_letters_sal`, `japanpost_letters_air`, `japanpost_letters_sea`, `japanpost_letters_registered_sal`, `japanpost_letters_registered_air`	Intl
Japan Post Domestic (Yuupack)	yuupack	`yuupack_regular`, `yuupack_fresh`, `yuupack_frozen`	Dom (JP)
Japan Post Domestic (Yuupacket)	yuupacket	`yuupacket_regular`	Dom (JP)
Japan Post Domestic (Yuumail)	yuumail	`yuumail_regular`	Dom (JP)
UPS	ups	`ups_saver`, `ups_worldwide_express`, `ups_worldwide_express_plus`, `ups_worldwide_expedited`, `ups_ground`, `ups_next_day`, `ups_next_day_saver`, `ups_second_day`, `ups_three_day_select`, `ups_worldwide_express_freight`, `ups_worldwide_express_freight_mid_day`	Intl
DHL	dhl	`dhl_express_worldwide`, `dhl_express_1200`, `dhl_express_0900`, `dhl_express_jumbo`	Intl
FedEx	fedex	`fedex_international_economy`, `fedex_international_first`, `fedex_international_priority`, `fedex_international_priority_express`, `fedex_international_priority_eod`, `fedex_international_connect_plus`	Intl
Sagawa	sagawa	`sagawa_fresh`, `sagawa_frozen`, `sagawa_plane`, `sagawa_regular`	Dom (JP)
Yamato	yamato	`yamato_regular`, `yamato_collect`, `yamato_direct_mail`, `yamato_time`, `yamato_freight_on_delivery`, `yamato_dispatch_multiple_units`, `yamato_nekopos`, `yamato_kuroneko_yuupacket`, `yamato_taqbin`, `yamato_taqbin_collect`	Dom (JP)
Yamato International	yamato_international	`yamato_international_regular`	Intl
Pegasus	pegasus	`pegasus_dhl`, `pegasus_ups`, `pegasus_ems`	Intl
Seino	seino	`seino_regular`, `seino_takuhai`, `seino_mini`, `seino_tsuhan`, `seino_business`	Dom (JP)
In-house shipping (for shipments without carriers or tracking like mail delivery)	custom	`custom_standard`	Dom (JP)

Carrier	Pack Size Values	Delivery Time Values
Sagawa	`60`, `80`, `100`, `140`, `160`	`not-specified`, `before-noon`, `12-14`, `14-16`, `16-18`, `18-20`, `19-21`, `18-21`
Japan Post Domestic (Yuupack)	`60`, `80`, `100`, `120`, `140`, `160`, `170`	`not-specified`, `before-noon`, `12-14`, `14-16`, `16-18`, `18-20`, `19-21`, `20-21`
Yamato		`not-specified`, `before-noon`, `14-16`, `16-18`, `18-20`, `19-21`, `before-ten`, `before-five`
Seino		`not-specified`, `before-noon`, `after-noon`, `9-12`, `12-17`, `17-20`

carrier_idstring

ID of carrier to use for a shipment. Possible values are the IDs of your active carriers. Useful if you have multiple accounts for a given carrier type. Intl, Dom (JP)

carrierstring

Type of carrier to use for a shipment. Possible values are: japanpost, ups, fedex, dhl, sagawa, yamato, yuupack, pegasus, seino. Intl, Dom (JP)

servicestring

The service name for the chosen carrier. See the list of possible services by carrier above. Intl, Dom (JP)

currencystring

The shipment currency of products, we accept only ISO 4217 values. Intl, Dom (JP)

datestring

The delivery date. YYYY-MM-DD format example 2018-09-20. If omitted, the blank is set (= the earliest date given by the shipping carrier) or the earliest date. Intl, Dom (JP)

timestring

The value of delivery time depends on the carrier, this option is available only for yamato, sagawa and yuupack, see the list above. Dom (JP)

shipment_datestring

String. The shipment date. YYYY-MM-DD format example 2018-09-18. If omitted, the date gets unspecified. This is mandatory for yamato only. Intl, Dom (JP)

insurancenumber

Amount to be covered by the carrier in the same currency as the shipment.
Supported carriers: japanpost, dhl, fedex, and ups.
If no insurance is needed, this field should be omitted. Intl

ref_numberstring

If you need to provide a reference number to the shipping label. Intl, Dom (JP)

delivery_notestring

If you need to provide some notes about delivery. Intl, Dom (JP)

signatureboolean

This is a paid service on some carriers. Intl

cool_optionsstring

Possible values are regular, fresh, and frozen. Dom (JP)

careobject

fragile: (boolean), side_up: (boolean), valuable_goods: (boolean), Dom (JP)

pack_sizenumber

The value of pack size depends on the carrier. See the list above. Dom (JP)

pack_amountnumber

Number. The value of pack amount. Dom (JP)

cash_on_deliveryobject

The total and tax amount of cash on delivery. amount: (integer), tax: (integer), Dom (JP)

return_labelboolean

Issue return labels simultaneously. If true is set for supported carriers (e.g. DHL), return labels get generated with multiple tracking numbers. Intl, Dom (JP)

print_start_locationnumber

Number. The position of the label in the A4 sheet. Only for yuupacket_regular, yuumail_regular, yamato_direct_mail, yamato_nekopos, yamato_kuroneko_yuupacket. Dom (JP)

shipping_feenumber

Number. Shipping fee to be included on the PDF commercial invoice for the shipment. Intl

security_serviceboolean

Valid for yuupack_regular shipments only. Possible value: true or false. Dom (JP)

consignee_tax_idstring

String. Tax ID for the receiver or importer in international orders (e.g., VAT ID, EORI). Supported carriers: JapanPost International, Pegasus, UPS, DHL, FedEx. Intl

discountnumber

Number. Percentage discount applied to each product's price. For example, if a product 'price' is 5000 and discount is 10, the final price becomes 4500. Intl

instructionstring

Special handling instructions for shipment creation. These values are only available when using Seino (西濃運輸) as the carrier: none, handling-caution, weird-caution, glass-caution, kowaremono, dry, precision-machinery, no-low-stack, no-horizontal-stack, no-flat-stack, no-standing-stack, no-top-bottom, no-cornering, valuable-goods, expensive

Pagination

These parameters and response fields are used for paginating through large datasets when listing resources.
They are only applicable to the List Shipments endpoint.

Request Parameters

created_afterstring

format 2018-09-20T00:00:00.000Z

created_beforestring

default today format 2018-09-20T00:00:00.000Z

limitnumber

default 50, max 250

pagenumber

default 1

Response Parameters

countnumber

Total number of data

current_pagenumber

The current response page (can be specified by request parameters)

pagesnumber

Total number of pages of responses (can be specified by request parameters)

Error

Error Code

Ship&co API has the following error codes.
Returns 200 for normal responses.

400

Validation errors due to incorrect or insufficient input

403

The API token is not specified or is incorrect

404

The specified data is not found

429

Too many requests (refer to Rate Limit for the details)

500

Internal errors

Error Response

Ship&co API returns the following error response.

debug_idstring

Unique ID for each API call to communicate with Ship&co

descriptionstring

Error long description

detailsstring

Error details with each item

linkstring

Link to the error contents

messagestring

Error short message

1{
2  "debug_id": "err_8953pxowmMt3YW2XQ",
3  "message": "INVALID",
4  "description": "Request is not well-formed, syntactically incorrect, or violates schema.",
5  "link": "https://developer.shipandco.com",
6  "details": [
7    {
8      "field": "address1",
9      "issue": "address1 is required"
10    },
11    {
12      "field": "country",
13      "issue": "country is required"
14    }
15  ]
16}