NAV Navbar
cURL Node.js
  • Overview
  • Authorization
  • Shipment
  • Error
  • Overview

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

    Register your Ship&Co account here

    API usage is very simple. You can complate with the following two steps.

    1. Authorization
    2. API Call

    Authorization

    Add the following HTTP headers to all API calls

    curl "EACH_API_END_POINT" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    
    const request = require("request");
    
    const options = {
      method: 'POST',
      url: 'https://app.shipandco.com/api/v1/shipments',
      headers:
       { 'x-access-token': 'YOUR_API_TOKEN_FROM_DASHBOARD',
         'content-type': 'application/json' },
      body: { *BODY CONTENT* },
      json: true
    };
    
    request(options, function (error, response, body) {
      if (error) throw new Error(error);
      console.log(body);
    });
    

    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 authrized and use our APIs.

    Follow the steps to get API token.

    1. Login 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 a shipment label

    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"
        }
      }
    
    const request = require('request');
    
    const options = {
      method: 'POST',
      url: 'https://app.shipandco.com/api/v1/shipments',
      headers: {
        'x-access-token': 'YOUR_API_TOKEN_FROM_DASHBOARD',
        'content-type': 'application/json',
      },
      body: {
        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: '4634.00',
            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',
        },
      },
      json: true,
    };
    
    request(options, function(error, response, body) {
      if (error) throw new Error(error);
    
      console.log(body);
    });
    

    The above request returns the following response.

    {
      "label": "https://.../tDAs4Te95AoYHJhn9.pdf"
    }
    

    Create a shipment label of the target carrier with the specified shipping address and item information.

    Request

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

    Response

    Item Note
    label Image information of the created label

    Error

    Ship&Co API has the following error codes.

    Returns 200 for normal responses.

    Error Code Note
    403 API token is not specified or incorrect
    400 Other handleable errors
    500 Internal errors