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

    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

    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. full_name, country, address1, city
    from_address Sender address. full_name, phone, country, address1, province
    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.
    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" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    The above request returns the following response.

    {
      "shipments": [
        {
          "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"
          }
        },
        {
          "id": "API-K3EDGXX9SF",
          "state": "active",
          "created_at": "2019-01-07T14:09:24.828Z",
          "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-08",
            "time": "16-18",
            "care": {
              "fragile": false,
              "side_up": false,
              "valuable_goods": false
            },
            "pick_up": false,
            "print_start_location": "4"
          },
          "delivery": {
            "carrier": "yamato",
            "method": "yamato_regular",
            "tracking_numbers": ["436966892191"],
            "label": "https://storage.googleapis.com/dev-shipandco/labels/201901/k3wWYYwk8Q8h46NcM/undefined.pdf"
          }
        }
      ],
      "count": 3,
      "pages": 2,
      "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`

    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-H8TNUMIUBL" \
      -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.

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

    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