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 an 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 APIs.

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

    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"
        },
        "parcels": [
          {
            "weight": 200,
            "amount": 1,
            "width": 10,
            "height": 10,
            "depth": 10
          }
        ],
        "products": [
          {
            "name": "Basket ball",
            "quantity": 2,
            "price": 4850,
            "hs_code": "HS9988",
            "hs_description": "Sports ball",
            "origin_country": "JP"
          }
        ],
        "setup": {
          "carrier": "japanpost",
          "service": "ems",
          "currency": "JPY",
          "date": "2018-07-12",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        }
      }'
    

    The above request returns the following response.

    {
      "id": "API-XY7SCJGCXO",
      "state": "active",
      "created_at": "2018-10-10T15:50:10.868Z",
      "parcels": [
        {
          "weight": 200,
          "amount": 1,
          "width": 10,
          "height": 10,
          "depth": 10
        }
      ],
      "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"
      },
      "options": {
        "common": {
          "insurance": 0,
          "ref_number": "",
          "delivery_note": ""
        },
        "international": {
          "return_label": false,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        },
        "japan": {
          "delivery_date": "2018-07-12",
          "shipment_type": "ems",
          "cash_on_delivery": false,
          "freight_on_delivery": false,
          "ahead_on_schedule": false,
          "care": {
            "fragile": false,
            "side_up": false,
            "valuable_goods": false
          },
          "package_number": "1",
          "pick_up": false
        }
      },
      "products": [],
      "delivery": {
        "carrier": "japanpost",
        "method": "ems",
        "tracking_numbers": ["EN022179102JP"],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201810/k3wWYYwk8Q8h46NcM/QFZT4vrm6bge73Bxg.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
    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-09-01T00:00:00.000Z&created_before=2018-09-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-H8TNUMIUBL",
          "state": "active",
          "created_at": "2018-09-24T15:37:33.995Z",
          "parcels": [
            {
              "weight": 200,
              "amount": 1,
              "width": 10,
              "height": 10,
              "depth": 10
            }
          ],
          "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"
          },
          "options": {
            "common": {
              "insurance": 0,
              "ref_number": "",
              "delivery_note": ""
            },
            "international": {
              "return_label": false,
              "signature": false,
              "duty_paid": false,
              "content_type": "MERCHANDISE"
            },
            "japan": {
              "delivery_date": "2018-07-12",
              "shipment_type": "ems",
              "cash_on_delivery": false,
              "freight_on_delivery": false,
              "ahead_on_schedule": false,
              "care": {
                "fragile": false,
                "side_up": false,
                "valuable_goods": false
              },
              "package_number": "1",
              "pick_up": false
            }
          },
          "products": [],
          "delivery": {
            "carrier": "japanpost",
            "method": "ems",
            "tracking_numbers": ["EN020057361JP"],
            "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
          }
        },
        {
          "id": "API-MIXKKUSCUD",
          "state": "active",
          "created_at": "2018-09-24T15:37:31.705Z",
          "parcels": [
            {
              "weight": 200,
              "amount": 1,
              "width": 10,
              "height": 10,
              "depth": 10
            }
          ],
          "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"
          },
          "options": {
            "common": {
              "insurance": 0,
              "ref_number": "",
              "delivery_note": ""
            },
            "international": {
              "return_label": false,
              "signature": false,
              "duty_paid": false,
              "content_type": "MERCHANDISE"
            },
            "japan": {
              "delivery_date": "2018-07-12",
              "shipment_type": "ems",
              "cash_on_delivery": false,
              "freight_on_delivery": false,
              "ahead_on_schedule": false,
              "care": {
                "fragile": false,
                "side_up": false,
                "valuable_goods": false
              },
              "package_number": "1",
              "pick_up": false
            }
          },
          "products": [],
          "delivery": {
            "carrier": "japanpost",
            "method": "ems",
            "tracking_numbers": ["EN021063567JP"],
            "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
          }
        }
      ],
      "count": 5,
      "pages": 3,
      "current_page": 1
    }
    

    List created shipments.

    Request

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

    Item Note
    state default `active`, possible values: `active, avoided, 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-H8TNUMIUBL",
      "state": "active",
      "created_at": "2018-09-24T15:37:33.995Z",
      "parcels": [
        {
          "weight": 200,
          "amount": 1,
          "width": 10,
          "height": 10,
          "depth": 10
        }
      ],
      "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"
      },
      "options": {
        "common": {
          "insurance": 0,
          "ref_number": "",
          "delivery_note": ""
        },
        "international": {
          "return_label": false,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        },
        "japan": {
          "delivery_date": "2018-07-12",
          "shipment_type": "ems",
          "cash_on_delivery": false,
          "freight_on_delivery": false,
          "ahead_on_schedule": false,
          "care": {
            "fragile": false,
            "side_up": false,
            "valuable_goods": false
          },
          "package_number": "1",
          "pick_up": false
        }
      },
      "products": [],
      "delivery": {
        "carrier": "japanpost",
        "method": "ems",
        "tracking_numbers": ["EN020057361JP"],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
      }
    }
    

    Find a Shipment with ID.

    Request

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

    Response

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

    Rate

    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"
        },
        "parcels": [
          {
            "weight": 200,
            "amount": 1,
            "width": 10,
            "height": 10,
            "depth": 10
          }
        ],
        "products": [
          {
            "name": "Basket ball",
            "quantity": 2,
            "price": 4850,
            "hs_code": "HS9988",
            "hs_description": "Sports ball",
            "origin_country": "JP"
          }
        ],
        "setup": {
          "carrier": "japanpost",
          "service": "ems",
          "currency": "JPY",
          "date": "2018-07-12",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        }
      }'
    

    The above request returns the following response.

    [
      {
        "carrier": "japanpost",
        "service": "ems",
        "currency": "JPY",
        "price": 2200,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "kakitome",
        "currency": "JPY",
        "price": 690,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "epacket",
        "currency": "JPY",
        "price": 785,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "sal",
        "currency": "JPY",
        "price": 280,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "epacketlight",
        "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": []
      },
      {
        "carrier": "japanpost",
        "service": "airmail",
        "currency": "JPY",
        "price": 420,
        "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.

    Common Definition

    Carrier And Services

    Carrier Value Service Values International / Domestic
    Japan Post japanpost ems, epacket, epacketlight, kakitome, airparcel, salparcel, seaparcel International
    UPS ups Saver, Worldwide Express, Worldwide Expedited, Worldwide Express Plus International
    DHL dhl EXPRESS WORLDWIDE, EXPRESS 12:00, EXPRESS 9:00, EXPRESS JUMBO International
    FedEx fedex International Economy, International First, International Priority International
    Sagawa sagawa fresh, frozen, plane, regular Domestic

    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