NAV Navbar
cURL
  • Overview
  • Authorization
  • Shipment
  • Rate
  • Carrier
  • 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.

    Diagram

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

    1. Authorization
    2. API Call

    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.

    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": "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",
          "service": "japanpost_ems",
          "currency": "JPY",
          "date": "2019-01-08",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false
        }
    }'
    

    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/adbmyPqo7ev9sNkpu.pdf"
      }
    }
    

    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.

    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.
    full_name, country, address1, province (for countries those have only), city (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.
    full_name, phone, country, address1, province (for countries those have only), city (for countries those have only)
    parcels Parcel information. For international shipping, at least one piece of information per parcel must be inputted
    products Product information. name, quantity, price, hs_description, origin_country
    customs Custom information.
    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

    Response

    Item Note
    id Shipment ID. Usable for GET.
    options Shipment Options.
    delivery.carrier Specified carrier name.
    delivery.tracking_numbers Shipment tracking #.
    delivery.label Created label image information.

    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.

    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": []
      },
      {
        "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"
        }
      }'
    

    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.

    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`.
    credentials Credentials required for using carrier systems. 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

    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.

    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

    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`. 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)
    cash_on_delivery Object. `amount`: (integer), `tax`: (integer) 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)

    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
    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