NAV Navbar
cURL
  • Overview
  • Authorization
  • Shipment
  • Rate
  • Carrier
  • Tracking
  • Address
  • Warehouse
  • Sub User
  • Common Definition
  • Error
  • Overview

    Welcome to the Ship&Co API Document! This document describes how to use our API.

    Register your Ship&Co account here

    API integration enables the following usecases.

    Who should read this document

    API processing overview

    Diagram

    Using our API is very simple. You can complete the process with the following two steps.

    1. Authorization
    2. API Call

    Try sample codes

    Disclaimer

    Authorization

    Add the following HTTP headers to all of your API calls

    curl "EACH_API_END_POINT" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    Replace `YOUR_API_TOKEN_FROM_DASHBOARD` with your obtained API token

    Setting API Token to HTTP headers that can be published in the Ship&Co dashboard enables you to be authorized and use our API.

    Follow the steps to get the API token.

    1. Login to the Ship&Co dashboard
    2. Click [Settings] and copy the text in [API Settings]>[Token]

    Dashboard

    Adding the copied API token to HTTP headers as follows enables you to use the API.

    x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD

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

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

    Shipment

    Create Shipment

    curl -v -X POST "https://app.shipandco.com/api/v1/shipments" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
      "to_address": {
        "full_name": "TEST TARO",
        "company": "",
        "email": "",
        "phone": "1111111111",
        "country": "JP",
        "address1": "京都市中京区八百屋町117",
        "address2": "",
        "province": "",
        "zip": "604-8072",
        "city": "京都府"
      },
      "from_address": {
        "full_name": "テスト",
        "company": "",
        "email": "",
        "phone": "08012341234",
        "country": "JP",
        "address1": "OSAKAFU",
        "address2": "",
        "province": "OSAKA",
        "zip": "1234567",
        "city": "IBARAKI SHI"
      },
      "products": [
        {
          "name": "Basket ball",
          "quantity": "2",
          "price": "4850",
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball2",
          "quantity": "2",
          "price": "4850",
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball3",
          "quantity": "2",
          "price": "4850",
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball4",
          "quantity": "2",
          "price": "4850",
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball5",
          "quantity": "2",
          "price": "4850",
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        }
      ],
      "parcels": [
        {
          "amount": "1",
          "width": "10",
          "height": "10",
          "depth": "10",
          "weight": 2000
        }
      ],
      "customs": {
        "duty_paid": false,
        "content_type": "MERCHANDISE"
      },
      "setup": {
        "carrier": "sagawa",
        "service": "sagawa_regular",
        "currency": "JPY",
        "date": "",
        "time": "",
        "insurance": 0,
        "ref_number": "",
        "delivery_note": "",
        "signature": false,
        "care": {
          "fragile": false,
          "side_up": false,
          "valuable_goods": false
        },
        "pack_size": "0",
        "pack_amount": 3,
        "cash_on_delivery": {
          "amount": 0,
          "tax": 0
        },
        "return_label": false,
        "test": true
      }
    }'
    

    The above request returns the following response.

    {
      "id": "API-QWMHHRLQS8",
      "state": "active",
      "test": true,
      "created_at": "2019-08-31T07:14:20.209Z",
      "to_address": {
        "full_name": "TEST TARO",
        "company": "",
        "address1": "京都市中京区八百屋町117",
        "address2": "",
        "city": "京都府",
        "province": "",
        "zip": "604-8072",
        "country": "JP",
        "phone": "1111111111",
        "email": ""
      },
      "from_address": {
        "full_name": "テスト",
        "company": "",
        "address1": "OSAKAFU",
        "address2": "",
        "city": "IBARAKI SHI",
        "province": "OSAKA",
        "zip": "1234567",
        "country": "JP",
        "phone": "08012341234",
        "email": ""
      },
      "products": [
        {
          "name": "Basket ball",
          "quantity": 2,
          "price": 4850,
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball2",
          "quantity": 2,
          "price": 4850,
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball3",
          "quantity": 2,
          "price": 4850,
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball4",
          "quantity": 2,
          "price": 4850,
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        },
        {
          "name": "Basket ball5",
          "quantity": 2,
          "price": 4850,
          "hs_code": "",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        }
      ],
      "setup": {
        "currency": "JPY",
        "insurance": 0,
        "ref_number": "",
        "delivery_note": "",
        "discount": 0,
        "pack_size": "0",
        "pack_amount": 3,
        "date": "",
        "time": "",
        "care": {
          "fragile": false,
          "side_up": false,
          "valuable_goods": false
        },
        "pick_up": false
      },
      "delivery": {
        "carrier": "sagawa",
        "method": "sagawa_regular",
        "tracking_numbers": [
          "514699854874"
        ],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201908/k3wWYYwk8Q8h46NcM/voxZSt9fYeeWzFssm.pdf",
        "warnings": [ "DUMMY_WARNING" ]
      }
    }
    

    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.

    About Test Environement: *Adding `"test": true` in `setup` enables you to create dummy labels not charged. No need to add credit card in your account for testing purpose, but the labels cannot be used to ship. Test labels are currently available only for UPS, FedEx, DHL, Sagawa and Yamato.

    Request

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

    Item Note Mandatory Fields
    to_address Reciever address.
    Note that `province` needs 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).
    full_name, phone (for some services only), country, address1, province (for countries those have only), city (for countries those have only), zip (for countries those have only)
    from_address Sender address.
    Note that `province` needs 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).
    full_name, phone, country, address1, province (for countries those have only), city (for countries those have only), zip (for countries those have only)
    parcels Parcel information. *For domestic shipping, do not use this parameter and use pack size and amount in `setup` instead. amount, width, height, depth (At least one piece of information per parcel must be inputted)
    products Product information. name, quantity, price, origin_country
    customs Custom information. content_type (for some services only)
    setup 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 not charged.
    carrier, service, currency

    The following are runnanle sample requests for some carriers to check what differ from each other in addressess or mandatory fields.

    Response

    Item Note
    id Shipment ID. Usable for GET.
    delivery.carrier Specified carrier name.
    delivery.tracking_numbers Shipment tracking numbers. If the returning label is generated, these are multiple.
    delivery.label Created label image information. If the returning label is generated, this has multiple pages.
    delivery.warnings Warning message shown if the carrier has specific one. (e.g. Ineigible to DHL PLT. If you receive DHL PLT warning, refer to this page)

    List Shipments

    curl -v -X GET "https://app.shipandco.com/api/v1/shipments?state=active&limit=2&page=1&created_after=2018-12-01T00:00:00.000Z&created_before=2019-01-30T00:00:00.000Z&carrier=sagawa" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    {
        "shipments": [
            {
                "id": "API-SGF5LYSJAF",
                "state": "active",
                "created_at": "2019-01-08T17:17:08.394Z",
                "to_address": {
                    "full_name": "太郎山田",
                    "address1": "京都市東山区",
                    "country": "JP",
                    "email": "yamada.taro@demo.com",
                    "phone": "08012341234",
                    "address2": "西海子町",
                    "address3": "神宮道",
                    "province": "京都府",
                    "zip": "6050012"
                },
                "from_address": {
                    "company": "株式会社ACME",
                    "address1": "中央区",
                    "country": "JP",
                    "email": "yamada.hanako@acme.com",
                    "phone": "08012341234",
                    "address2": "日本橋堀留町",
                    "address3": "タワー #1001",
                    "province": "東京都",
                    "zip": "1030012"
                },
                "products": [
                    {
                        "name": "Basket ball",
                        "quantity": 2,
                        "price": 4850,
                        "hs_code": ""
                    }
                ],
                "setup": {
                    "currency": "JPY",
                    "insurance": 0,
                    "ref_number": "",
                    "delivery_note": "",
                    "discount": 0,
                    "pack_size": "60",
                    "pack_amount": 1,
                    "date": "2019-01-10",
                    "time": "16-18",
                    "care": {
                        "fragile": false,
                        "side_up": false,
                        "valuable_goods": false
                    },
                    "pick_up": false,
                    "print_start_location": "4"
                },
                "delivery": {
                    "carrier": "sagawa",
                    "method": "sagawa_regular",
                    "tracking_numbers": [
                        "514699818076"
                    ],
                    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/WgnXig8zR6hEvZLWE.pdf"
                }
            },
            {
                "id": "API-RXILYS438A",
                "state": "active",
                "created_at": "2019-01-08T17:13:19.968Z",
                "to_address": {
                    "full_name": "太郎山田",
                    "address1": "京都市東山区",
                    "country": "JP",
                    "email": "yamada.taro@demo.com",
                    "phone": "08012341234",
                    "address2": "西海子町",
                    "address3": "神宮道",
                    "province": "京都府",
                    "zip": "6050012"
                },
                "from_address": {
                    "company": "株式会社ACME",
                    "address1": "中央区",
                    "country": "JP",
                    "email": "yamada.hanako@acme.com",
                    "phone": "08012341234",
                    "address2": "日本橋堀留町",
                    "address3": "タワー #1001",
                    "province": "東京都",
                    "zip": "1030012"
                },
                "products": [
                    {
                        "name": "Basket ball",
                        "quantity": 2,
                        "price": 4850,
                        "hs_code": ""
                    }
                ],
                "setup": {
                    "currency": "JPY",
                    "insurance": 0,
                    "ref_number": "",
                    "delivery_note": "",
                    "discount": 0,
                    "pack_size": "60",
                    "pack_amount": 1,
                    "date": "2019-01-10",
                    "time": "16-18",
                    "care": {
                        "fragile": false,
                        "side_up": false,
                        "valuable_goods": false
                    },
                    "pick_up": false,
                    "print_start_location": "4"
                },
                "delivery": {
                    "carrier": "sagawa",
                    "method": "sagawa_regular",
                    "tracking_numbers": [
                        "514699818065"
                    ],
                    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/Fu8f5dvB5zrmBTHfh.pdf"
                }
            },
            {
                "id": "API-Y72ITP6P8G",
                "state": "active",
                "created_at": "2019-01-08T17:05:12.663Z",
                "to_address": {
                    "full_name": "太郎山田",
                    "address1": "京都市東山区",
                    "country": "JP",
                    "email": "yamada.taro@demo.com",
                    "phone": "08012341234",
                    "address2": "西海子町",
                    "address3": "神宮道",
                    "province": "京都府",
                    "zip": "6050012"
                },
                "from_address": {
                    "company": "株式会社ACME",
                    "address1": "中央区",
                    "country": "JP",
                    "email": "yamada.hanako@acme.com",
                    "phone": "08012341234",
                    "address2": "日本橋堀留町",
                    "address3": "タワー #1001",
                    "province": "東京都",
                    "zip": "1030012"
                },
                "products": [
                    {
                        "name": "Basket ball",
                        "quantity": 2,
                        "price": 4850,
                        "hs_code": ""
                    }
                ],
                "setup": {
                    "currency": "JPY",
                    "insurance": 0,
                    "ref_number": "",
                    "delivery_note": "",
                    "discount": 0,
                    "pack_size": "60",
                    "pack_amount": 1,
                    "date": "2019-01-10",
                    "time": "16-18",
                    "care": {
                        "fragile": false,
                        "side_up": false,
                        "valuable_goods": false
                    },
                    "pick_up": false,
                    "print_start_location": "4"
                },
                "delivery": {
                    "carrier": "sagawa",
                    "method": "sagawa_regular",
                    "tracking_numbers": [
                        "514699818054"
                    ],
                    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/dJt72M3PhJQo9pmjE.pdf"
                }
            },
            {
                "id": "API-Q9CASGOIC9",
                "state": "active",
                "created_at": "2019-01-08T16:56:16.944Z",
                "to_address": {
                    "full_name": "太郎山田",
                    "address1": "京都市東山区",
                    "country": "JP",
                    "email": "yamada.taro@demo.com",
                    "phone": "08012341234",
                    "address2": "西海子町",
                    "address3": "神宮道",
                    "province": "京都府",
                    "zip": "6050012"
                },
                "from_address": {
                    "company": "株式会社ACME",
                    "address1": "中央区",
                    "country": "JP",
                    "email": "yamada.hanako@acme.com",
                    "phone": "08012341234",
                    "address2": "日本橋堀留町",
                    "address3": "タワー #1001",
                    "province": "東京都",
                    "zip": "1030012"
                },
                "products": [
                    {
                        "name": "Basket ball",
                        "quantity": 2,
                        "price": 4850,
                        "hs_code": ""
                    }
                ],
                "setup": {
                    "currency": "JPY",
                    "insurance": 0,
                    "ref_number": "",
                    "delivery_note": "",
                    "discount": 0,
                    "pack_size": "60",
                    "pack_amount": 1,
                    "date": "2019-01-10",
                    "time": "16-18",
                    "care": {
                        "fragile": false,
                        "side_up": false,
                        "valuable_goods": false
                    },
                    "pick_up": false,
                    "print_start_location": "4"
                },
                "delivery": {
                    "carrier": "sagawa",
                    "method": "sagawa_regular",
                    "tracking_numbers": [
                        "514699818043"
                    ],
                    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/74FBe7MnjmQ3eM66b.pdf"
                }
            },
            {
                "id": "API-6E53FMVTZF",
                "state": "active",
                "created_at": "2019-01-08T16:55:44.228Z",
                "to_address": {
                    "full_name": "太郎山田",
                    "address1": "京都市東山区",
                    "country": "JP",
                    "email": "yamada.taro@demo.com",
                    "phone": "08012341234",
                    "address2": "西海子町",
                    "address3": "神宮道",
                    "province": "京都府",
                    "zip": "6050012"
                },
                "from_address": {
                    "company": "株式会社ACME",
                    "address1": "中央区",
                    "country": "JP",
                    "email": "yamada.hanako@acme.com",
                    "phone": "08012341234",
                    "address2": "日本橋堀留町",
                    "address3": "タワー #1001",
                    "province": "東京都",
                    "zip": "1030012"
                },
                "products": [
                    {
                        "name": "Basket ball",
                        "quantity": 2,
                        "price": 4850,
                        "hs_code": ""
                    }
                ],
                "setup": {
                    "currency": "JPY",
                    "insurance": 0,
                    "ref_number": "",
                    "delivery_note": "",
                    "discount": 0,
                    "pack_size": "60",
                    "pack_amount": 1,
                    "date": "2019-01-10",
                    "time": "16-18",
                    "care": {
                        "fragile": false,
                        "side_up": false,
                        "valuable_goods": false
                    },
                    "pick_up": false,
                    "print_start_location": "4"
                },
                "delivery": {
                    "carrier": "sagawa",
                    "method": "sagawa_regular",
                    "tracking_numbers": [
                        "514699818032"
                    ],
                    "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/2GAfFX6Yy87cCtRqo.pdf"
                }
            }
        ],
        "count": 5,
        "pages": 1,
        "current_page": 1
    }
    

    Get a list of created shipments.

    Request

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

    Item Note
    state default `active`, possible values: `active, voided, any`
    carrier Specify `type` of the carrier given by List Carriers

    See GET Parameters for more items.

    Response

    Array of created shipments. See Create Shipment for more details.

    See GET Response for more items.

    Get Shipment

    curl -v -X GET "https://app.shipandco.com/api/v1/shipments/API-O8APFNW9S8" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    {
      "id": "API-O8APFNW9S8",
      "state": "active",
      "created_at": "2019-01-07T14:15:01.151Z",
      "to_address": {
        "full_name": "John Doe",
        "company": "ACME",
        "address1": "Rua Maria Matos, 32",
        "country": "PT",
        "email": "john@doe.io",
        "phone": "0901231234",
        "address2": "",
        "city": "CHARNECA DA CAPARICA",
        "province": "SETUBAL",
        "zip": "2820-344"
      },
      "from_address": {
        "full_name": "Yamada Taro",
        "company": "World Company",
        "address1": "OSAKAFU",
        "country": "JP",
        "email": "ytaro@worldcompany.com",
        "phone": "08012341234",
        "address2": "OTECHO",
        "city": "IBARAKI SHI",
        "province": "OSAKA",
        "zip": "5670883"
      },
      "products": [
        {
          "name": "Basket ball",
          "quantity": 2,
          "price": 4850,
          "hs_code": "HS9988",
          "hs_description": "Sports ball",
          "origin_country": "JP"
        }
      ],
      "parcels": [
        {
          "weight": 200,
          "amount": 1,
          "width": 10,
          "height": 10,
          "depth": 10
        }
      ],
      "customs": {
        "duty_paid": false,
        "content_type": "MERCHANDISE"
      },
      "setup": {
        "currency": "JPY",
        "insurance": 0,
        "ref_number": "",
        "delivery_note": "",
        "discount": 0,
        "return_label": false,
        "signature": false
      },
      "delivery": {
        "carrier": "japanpost",
        "method": "japanpost_ems",
        "tracking_numbers": ["EN027977320JP"],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/undefined.pdf"
      }
    }
    

    Get a shipment by the shipment ID.

    Request

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

    Response

    Only one shipment is displayed. See Create Shipment for more details.

    Delete Shipment

    curl -v -X DELETE "https://app.shipandco.com/api/v1/shipments/API-O8APFNW9S8" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    "Shipment API-O8APFNW9S8 deleted."
    

    Delete a shipment by the shipment ID.

    Request

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

    Response

    The resule message is displayed.

    Rate

    List Rates

    curl -v -X POST "https://app.shipandco.com/api/v1/rates" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
        "to_address": {
          "full_name": "John Doe",
          "company": "ACME",
          "email": "john@doe.io",
          "phone": "0901231234",
          "country": "PT",
          "address1": "Rua Maria Matos, 32",
          "address2": "",
          "province": "SETUBAL",
          "zip": "2820-344",
          "city": "CHARNECA DA CAPARICA"
        },
        "from_address": {
          "full_name": "Yamada Taro",
          "company": "World Company",
          "email": "ytaro@worldcompany.com",
          "phone": "08012341234",
          "country": "JP",
          "address1": "OSAKAFU",
          "address2": "OTECHO",
          "province": "OSAKA",
          "zip": "5670883",
          "city": "IBARAKI SHI"
        },
        "products": [
          {
            "name": "Basket ball",
            "quantity": 2,
            "price": 4850,
            "hs_code": "HS9988",
            "hs_description": "Sports ball",
            "origin_country": "JP"
          }
        ],
        "parcels": [
          {
            "weight": 200,
            "amount": 1,
            "width": 10,
            "height": 10,
            "depth": 10
          }
        ],
        "customs": {
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        },
        "setup": {
          "carrier": "japanpost",
          "currency": "JPY",
          "date": "2019-01-08",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false
        }
    }'
    

    The above request returns the following response.

    [
      {
        "carrier": "japanpost",
        "service": "japanpost_ems",
        "currency": "JPY",
        "price": 2200,
        "surcharges": [
          {
           "type": "frozen",
           "amount": "324"
          }
        ]
      },
      {
        "carrier": "japanpost",
        "service": "japanpost_registered_mail",
        "currency": "JPY",
        "price": 690,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "japanpost_epacket",
        "currency": "JPY",
        "price": 785,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "japanpost_epacket_light",
        "currency": "JPY",
        "price": 620,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "airparcel",
        "currency": "JPY",
        "price": 2500,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "salparcel",
        "currency": "JPY",
        "price": 2700,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "seaparcel",
        "currency": "JPY",
        "price": 1800,
        "surcharges": []
      }
    ]
    

    Based on the entered shipping information, the fee for each service of the specified carrier is displayed in a list.

    Request

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

    The same as the shipment creation eliminating `service`. For more details, see Create Shipment.

    Response

    Array of rates of each service. For more details, see Carrier And Services.

    Carrier

    Register Carrier

    curl -v -X POST "https://app.shipandco.com/api/v1/carriers" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "dhl",
        "credentials": {
          "account_number": "123456789"
        },
        "settings": {
          "label": {
            "hide_account": true,
            "extra_page":  true
          }
        }
      }'
    

    The above request returns the following response.

    {
      "id": "g3buDjYMCXaj6zNCv",
      "type": "dhl",
      "state": "active",
      "created_at": "2019-02-25T11:58:57.852Z",
      "updated_at": "2019-02-25T11:58:57.852Z",
      "credentials": {
        "account_number": "*********"
     } 
    }
    

    Register a Carrier. For more details, see our site.

    Request

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

    Item Note
    type Type of carrier you want to add. Possible values are: `japanpost`, `ups`, `fedex`, `dhl`, `dhlecasia`, `sagawa`, `yamato`, `yuupack`, `pegasus`, `ecms`.
    credentials Credentials required for using carrier systems. The parameters inside this are different from each other. See the following for the details.
    settings Settings specific to each carrier. The parameters inside this are different from each other. See the following for the details.

    Credentials parameter by carrier

    DHL

    account_number: String, required

    UPS

    account_number: String, required

    user_name: String, required

    password: String, required

    access_key: String, required

    FedEx

    account_number: String, required

    Japan Post International

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

    Sagawa

    account_number: String, required

    key: String, required

    password: String, required

    In order to get the key and password from Sagawa a form must be filled and sent to Sagawa who will send back those information and automatically activate users account. It takes 5 to 8 business day. Link to the form will be available shortly.

    Japan Post Domestic (Yuupack)

    user_id: String, required

    In order to get the user_id from Japan Post a form must be filled and sent to them who will send back those information to the user. It takes 5 to 8 business day. Link to the form will be available shortly.

    Yamato

    key: String, required

    freight_number: String, (default: '01')

    Pegasus

    user_id: String, required

    password: String, required

    AUSTRALIA POST

    auspost_account_number: String, required

    startrack_account_number: String, required

    key: String, required

    secret: String, required

    DHL eCommerce Asia

    sold_to: String, required

    pick_up: String, required

    prefix: String, required

    ECMS

    merchant_id: String, required

    consumer_key: String, required

    consumer_secret: String, required

    Settings by carrier

    DHL

    label.hide_account: Boolean. Whether to print account information on labels or not.

    label.extra_page: Boolean. Whether to create a page for archiving or not.

    Response

    Registered Carrier information with its ID

    List Carriers

    curl -v -X GET "https://app.shipandco.com/api/v1/carriers" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    [
        {
            "id": "GZDZQNo7zyxr4sbXc",
            "type": "yuupacket",
            "state": "active",
            "created_at": "2019-01-07T14:24:13.045Z",
            "updated_at": "2019-01-07T14:24:13.045Z",
            "credentials": {
                "user_id": "***********"
            }
        },
        {
            "id": "FbqDPqcBL6AL7PwAo",
            "type": "yuupack",
            "state": "active",
            "created_at": "2019-01-07T14:24:13.042Z",
            "updated_at": "2019-01-07T14:24:13.042Z",
            "credentials": {
                "user_id": "***********"
            }
        },
        {
            "id": "7iuaQaEp8fasKCzgD",
            "type": "yamato",
            "state": "active",
            "created_at": "2019-01-07T14:06:13.197Z",
            "updated_at": "2019-01-07T14:06:13.197Z",
            "credentials": {
                "key": "*********************************************************",
                "freight_number": "**"
            }
        },
        {
            "id": "tbEuFScyfSQMx7bN8",
            "type": "sagawa",
            "state": "active",
            "created_at": "2019-01-07T14:06:39.627Z",
            "updated_at": "2019-01-07T14:08:45.817Z",
            "credentials": {
                "key": "********",
                "password": "************************",
                "account_number": "***********",
                "account_key_number": ""
            }
        },
        {
            "id": "CFjQRubN5jhhT5hTb",
            "type": "japanpost",
            "state": "active",
            "created_at": "2018-09-24T15:33:58.145Z",
            "updated_at": "2018-09-24T15:33:58.145Z",
            "credentials": {
                "customer_numbers": "****"
            }
        }
    ]
    

    Get a list of registered carriers information.

    Request

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

    Response

    Array of registered carriers inoformation.

    Delete Carrier

    curl -v -X DELETE "https://app.shipandco.com/api/v1/carriers/GZDZQNo7zyxr4sbXc" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    "Carrier GZDZQNo7zyxr4sbXc deleted."
    

    Delete a carrier by the carrier ID.

    Request

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

    Response

    The resule message is displayed.

    Tracking

    Get Tracking

    curl -v -X GET "https://app.shipandco.com/api/v1/tracking/japanpost/RN004792035JP" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    {
        "requested_at": "2019-05-22T14:52:35.155Z",
        "carrier": "japanpost",
        "tracking_number": "RN004792035JP",
        "service": "Registered Mail / Insured Mail",
        "from_address": {},
        "to_address": {},
        "current_status": {
            "date": "2019-05-20T17:30:00.000Z",
            "status": "Arrival at outward office of exchange",
            "details": "",
            "location": "OSAKA"
        },
        "history": [
            {
                "date": "2019-05-20T07:45:00.000Z",
                "status": "Posting/Collection",
                "details": "",
                "location": "OSAKA"
            },
            {
                "date": "2019-05-20T17:30:00.000Z",
                "status": "Arrival at outward office of exchange",
                "details": "",
                "location": "OSAKA"
            }
        ]
    }
    

    Get a tracking information with a carrier and its tracking number.

    Request

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

    Response

    Carrier's tracking information

    Address

    Register Address

    curl -v -X POST "https://app.shipandco.com/api/v1/addresses" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
       "full_name": "Ship Co",
       "company": "Ship&Co",
       "email": "shipco@shipandco.com",
       "phone": "0312345678",
       "country": "JP",
       "address1": "chukyo-ku",
       "address2": "",
       "address3": "",
       "province": "Kyoto-fu",
       "zip": "123-4567",
       "city": "Kyoto-shi"
    }'
    

    The above request returns the following response.

    {
        "id": "kr54qe8YPdc5HZSBu",
        "created_at": "2019-01-12T09:04:43.619Z",
        "updated_at": "2019-01-12T09:04:43.619Z",
        "address": {
            "full_name": "Ship Co",
            "company": "Ship&Co",
            "address1": "chukyo-ku",
            "address2": "",
            "address3": "",
            "city": "Kyoto-shi",
            "province": "Kyoto-fu",
            "zip": "123-4567",
            "country": "JP",
            "phone": "0312345678",
            "email": "shipco@shipandco.com"
        }
    }
    

    Register a shipping address.

    Request

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

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

    Response

    Registered shipping address information with its ID

    List Addresses

    curl -v -X GET "https://app.shipandco.com/api/v1/addresses" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    [
        {
            "id": "dC32vpNEja8W7WNwR",
            "created_at": "2019-01-12T08:32:55.411Z",
            "updated_at": "2019-01-12T08:32:55.411Z",
            "address": {
                "full_name": "John Doe",
                "company": "ACME",
                "address1": "Rua Maria Matos, 32",
                "address2": "",
                "address3": "",
                "city": "CHARNECA DA CAPARICA",
                "province": "SETUBAL",
                "zip": "2820-344",
                "country": "PT",
                "phone": "0901231234",
                "email": "john@doe.io"
            }
        },
        {
            "id": "kr54qe8YPdc5HZSBu",
            "created_at": "2019-01-12T09:04:43.619Z",
            "updated_at": "2019-01-12T09:04:43.619Z",
            "address": {
                "full_name": "Ship Co",
                "company": "Ship&Co",
                "address1": "chukyo-ku",
                "address2": "",
                "address3": "",
                "city": "Kyoto-shi",
                "province": "Kyoto-fu",
                "zip": "123-4567",
                "country": "JP",
                "phone": "0312345678",
                "email": "shipco@shipandco.com"
            }
        }
    ]
    

    Get a list of registered shipping addresses information.

    Request

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

    Response

    Array of registered shipping addresses inoformation.

    Warehouse

    Register Warehouse

    curl -v -X POST "https://app.shipandco.com/api/v1/warehouses" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
       "full_name": "",
       "full_name_kanji": "",
       "company": "ACME",
       "company_kanji": "株式会社ACME",
       "email": "",
       "phone": "090-1234-5678",
       "country": "JP",
       "address1": "HIGASHIYAMA KU",
       "address2": "SAIKAISHICHO",
       "province": "KYOTO",
       "address1_kanji": "京都市東山区",
       "address2_kanji": "西海子町",
       "address3_kanji": "",
       "province_kanji": "京都府",
       "zip": "604-0012",
       "city": "KYOTO SHI"
    }'
    

    The above request returns the following response.

    {
        "id": "cki5wYEHddBZuEtPv",
        "created_at": "2019-01-31T07:34:25.071Z",
        "updated_at": "2019-01-31T07:34:25.071Z",
        "address": {
            "full_name": "",
            "company": "ACME",
            "address1": "HIGASHIYAMA KU",
            "address2": "SAIKAISHICHO",
            "city": "KYOTO SHI",
            "province": "KYOTO",
            "zip": "604-0012",
            "country": "JP",
            "phone": "090-1234-5678",
            "email": "",
            "full_name_kanji": "",
            "company_kanji": "株式会社ACME",
            "address1_kanji": "京都市東山区",
            "address2_kanji": "西海子町",
            "address3_kanji": "",
            "province_kanji": "京都府"
        }
    }
    

    Register a warehouse.

    Request

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

    Warehouse information to register

    Response

    Registered warehouse information with its ID

    List Warehouses

    curl -v -X GET "https://app.shipandco.com/api/v1/warehouses" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    [
        {
            "id": "cki5wYEHddBZuEtPv",
            "created_at": "2019-01-31T07:34:25.071Z",
            "updated_at": "2019-01-31T07:34:25.071Z",
            "address": {
                "full_name": "",
                "company": "ACME",
                "address1": "HIGASHIYAMA KU",
                "address2": "SAIKAISHICHO",
                "city": "KYOTO SHI",
                "province": "KYOTO",
                "zip": "604-0012",
                "country": "JP",
                "phone": "090-1234-5678",
                "email": "",
                "full_name_kanji": "",
                "company_kanji": "株式会社ACME",
                "address1_kanji": "京都市東山区",
                "address2_kanji": "西海子町",
                "address3_kanji": "",
                "province_kanji": "京都府"
            }
        },
        {
            "id": "phuAH6qFvoxdASoCr",
            "created_at": "2019-01-31T07:37:46.332Z",
            "updated_at": "2019-01-31T07:37:46.332Z",
            "address": {
                "full_name": "John Doe",
                "company": "ACME",
                "address1": "Rua Maria Matos, 32",
                "address2": "",
                "address3": "",
                "city": "CHARNECA DA CAPARICA",
                "province": "SETUBAL",
                "zip": "2820-344",
                "country": "PT",
                "phone": "0901231234",
                "email": "john@doe.io"
            }
        }
    ]
    

    Get a list of registered warehouse information.

    Request

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

    Response

    Array of registered warehouse inoformation.

    Sub User

    Sub users can have each token to call APIs with data segmented belonging to a regular account created from Ship&Co dasiboard. Note that Sub User API itself can accpet regular accounts tokens only.

    Register Sub User

    curl -v -X POST "https://app.shipandco.com/api/v1/sub-users" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
        "contact": {
          "first_name": "John",
          "last_name": "Doe",
          "company": "ACME"
        },
        "email": "email@test.com",
        "api_token": true
    }'
    

    The above request returns the following response.

    {
      "id": "f1f97cfa813c828a73528989da671a81",
      "created_at": "2019-02-25T11:12:14.021Z",
      "email": "email@test.com",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
      "first_name": "John",
      "last_name": "Doe",
      "company": "ACME"
    }
    

    Register a Sub User.

    Request

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

    Sub User information to register. To create a Sub User we need an email address and some minimum contact informations.

    Item Note
    email Required. Key of sub users
    contact first_name, last_name, full_name (optinal), company
    api_token Request a token or not.

    Response

    Registered Sub User information with its ID and API token. Generated API token can be used for other APIs.

    List Sub Users

    curl -v -X GET "https://app.shipandco.com/api/v1/sub-users" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    [
        {
            "id": "f1f97cfa813c828a73528989da671a81",
            "created_at": "2019-02-25T11:12:14.021Z",
            "email": "email@test.com",
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
            "first_name": "John",
            "last_name": "Doe",
            "company": "ACME"
        },
        {
            "id": "929ab359ada3fa5c7bf53bff7ffcbe58",
            "created_at": "2019-02-26T11:08:13.749Z",
            "email": "email2@test.com",
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjUzam9qand4ejlQdWZzRXp4IiwiaWF0IjoxNTUxMTc5MjkzfQ.RLb2jWjwo9FZwP3MSyyDYkbQZMTtmjMvTYql-dfgk1o",
            "first_name": "John 2",
            "last_name": "Doe 2",
            "company": "ACME 2"
        }
    ]
    

    Get a list of registered sub user information.

    Request

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

    Response

    Array of registered sub user inoformation.

    Get Sub User

    curl -v -X GET "https://app.shipandco.com/api/v1/sub-users/f1f97cfa813c828a73528989da671a81" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    {
      "id": "f1f97cfa813c828a73528989da671a81",
      "created_at": "2019-02-25T11:12:14.021Z",
      "email": "email@test.com",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhYXNhZVBwNlpGWUZSZ1FzIiwiaWF0IjoxNTUxMDkzMTM0fQ.gBUpoCpFbIt26DiezI4liHWel9KP47-p-Uw-Q3Ush6k",
      "first_name": "John",
      "last_name": "Doe",
      "company": "ACME"
    }
    

    Get a sub user by the sub user ID.

    Request

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

    Response

    Only one sub user is displayed.

    Refresh Sub User

    curl -v -X POST "https://app.shipandco.com/api/v1/sub-users/f1f97cfa813c828a73528989da671a81" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

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

    Recreate API token of a sub user.

    Request

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

    Response

    Recreated API token

    Delete Sub User

    curl -v -X DELETE "https://app.shipandco.com/api/v1/sub-users/f1f97cfa813c828a73528989da671a81" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

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

    Delete a sub user by the carrier ID.

    Request

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

    Response

    The resule message is displayed.

    Common Definition

    Carrier And Services

    Carrier Value Service Values Intl / Dom (JP)
    Japan Post International japanpost japanpost_ems, japanpost_epacket, japanpost_epacket_light, japanpost_registered_mail, japanpost_economy_air, japanpost_airmail Intl
    Japan Post Domestic (Yuupack) yuupack yuupack_regular, yuupack_fresh, yuupack_frozen, regular Dom (JP)
    UPS ups ups_saver, ups_worldwide_express, ups_worldwide_express_plus, ups_worldwide_expedited Intl
    DHL dhl dhl_express_worldwide, dhl_express_1200, dhl_express_0900, dhl_express_jumbo Intl
    DHL eCommerce Asia dhlecasia dhlec_asia_pps, dhlec_asia_pkd, dhlec_asia_ple, dhlec_asia_plt, dhlec_asia_pld, dhlec_asia_pkg Intl
    FedEx fedex fedex_international_economy, fedex_international_first, fedex_international_priority 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_nekopos, yamato_taqbin, yamato_taqbin_collect Dom (JP)
    Pegasus pegasus pegasus_dhl, pegasus_ups, pegasus_ems Intl
    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
    Item Note Intl / Dom (JP)
    carrier String. Type of carrier to use for a shipment. Possible values are: `japanpost`, `ups`, `fedex`, `dhl`, `dhlecasia`, `sagawa`, `yamato`, `yuupack`, `pegasus`. Intl, Dom (JP)
    service String. The service name for the chosen carrier. See the list of possible services by carrier above. Intl, Dom (JP)
    currency String. The shipment currency, we accept only ISO 4217 values. Intl, Dom (JP)
    date String. The date of shipment. ISO 8601 format example `2018-09-20T00:00:00.000Z` Intl, Dom (JP)
    time String. The value of delivery time depends on the carrier, this option is avaialble only for `yamato`, `sagawa` and `yuupack`, see the list above. Dom (JP)
    insurance Number. Amount to be insured in the same currency as the shipment. Only for `japanpost`, `dhl`, `dhlecasia`, `ups` and `fedex`. *Set `0` for no insurance. Intl
    ref_number String. If you need to provide a reference number to the shipping label. Intl, Dom (JP)
    delivery_note String. If you need to provide some notes about delivery. Intl, Dom (JP)
    signature Boolean. This is a paid service on some carriers. Intl
    cool_options String. Possible values are `regular`, `fresh` and `frozen`. Dom (JP)
    care Object. `fragile`: (boolean), `side_up`: (boolean), `valuable_goods`: (boolean) Dom (JP)
    pack_size String. The value of pack size depends on the carrier. See the list above. Dom (JP)
    pack_amount Number. The value of pack amount. Dom (JP)
    cash_on_delivery Object. `amount`: (integer), `tax`: (integer) Dom (JP)
    return_label Boolaean. Simultaneous publishment of returning labels. If `true` is set for supported carriers (e.g. DHL), returning labels get generated with multiple tracking numbers. Intl, Dom (JP)

    GET Parameters

    Item Note
    limit default `50`, max `250`
    page default `1`
    created_after format `2018-09-20T00:00:00.000Z`
    created_before default `today` format `2018-09-20T00:00:00.000Z`

    GET Response

    Item Note
    count Total number of data
    pages Total number of pages of responses (can be specified by GET Parameters)
    current_page The current response page (can be specified by GET Parameters)

    Rate Limit

    Number of API calls per unite time has some limitation. If you exceed it, `Too many requests` error occurs. You can check the details of the limitation to avoid it with the following response header items.

    Item Note
    x-api-call-limit The amount available/total amount per unit time. API calls with the available amount 0 produce the error above
    x-api-call-reset The timestamp when the amount available above resets to total

    Error

    Error Code

    Ship&Co API has the following error codes.

    Returns 200 for normal responses.

    Error Code Note
    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

    {
      "debug_id": "err_8953pxowmMt3YW2XQ",
      "message": "INVALID",
      "description": "Request is not well-formed, syntactically incorrect, or violates schema.",
      "link": "https://developer.shipandco.com",
      "details": [
        {
          "field": "address1",
          "issue": "address1 is required"
        },
        {
          "field": "country",
          "issue": "country is required"
        }
      ],
    }
    

    Ship&Co API returns the following error response.

    Item Note
    debug_id Unique ID for each API call to communicate with Ship&Co
    message Error short message
    description Error long description
    link Link to the error contents
    details Error details with each item