Chit Chats API (1.0)

To use the API, users must know their client ID and generate an API access token. This can be done in the Settings > Account > API Access Tokens section of the Chit Chats website. Please handle access tokens with the same level of security as passwords; do not share them or commit them to source code repositories. Deleting an access token will immediately revoke its access.

All URLs start with https://chitchats.com/api/v1/clients/<YOUR_CLIENT_ID>/. URLs are HTTPS only.

Each request must include the API access token in the Authorization header and client ID in the url.

To try the cURL examples throughout this doc, in your terminal run:

export ACCESS_TOKEN=<YOUR_ACCESS_TOKEN>
export CLIENT_ID=<YOUR_CLIENT_ID>

Then you should be able to copy/paste any example from the docs. After pasting a cURL example, you can pipe it to a JSON pretty printer to make it more readable. Try jsonpp or json_pp on OSX:

In cURL, to list all shipments:

curl -s -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments?limit=100&page=1" | json_pp

To create a shipment, you also have to include the Content-Type header and the JSON data:

curl -X POST \
  -H "Authorization: $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "address_1": "123 ANYWHERE ST.",
    "city": "Vancouver",
    "province_code": "BC",
    "postal_code": "V6K 1A1",
    "country_code": "CA",
    "description": "Hand made bracelet",
    "value": "85",
    "value_currency": "usd",
    "package_type": "parcel",
    "size_unit": "cm",
    "size_x": 10,
    "size_y": 5,
    "size_z": 2.5,
    "weight_unit": "g",
    "weight": 250,
    "postage_type": "chit_chats_canada_tracked",
    "ship_date": "today"
  }' \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments"

We use JSON for all API data. The style is no root element and snake_case for object keys. This means that you have to send the Content-Type header Content-Type: application/json; charset=utf-8 when you're POSTing or PUTing data.

Most collection APIs paginate their results. Use the limit and page query parameters to control pagination. The limit param has a maximum value of 1000.

By default, you may perform up to 2,000 requests per 5-minute period. Exceeding this limit will result in a 429 Too Many Requests response for subsequent requests. Check the Retry-After header to learn how many seconds to wait before retrying the request.

We run a sandbox site at https://staging.chitchats.com that you can use to test your API integration. To add credits use credit card number 4242 4242 4242 4242 with any expiry and CVC.

You can get public tracking events as JSON by adding a .json suffix to the public tracking URL.

E.g., if the Chit Chats shipment ID is Y2F0B87U1H you can get the public tracking page at: https://chitchats.com/tracking/y2f0b87u1h

and the JSON tracking page at: https://chitchats.com/tracking/y2f0b87u1h.json

Sample Response:

{
    "shipment":
    {
        "shipment_id": "Y2F0B87U1H",
        "to_city": "ALBUQUERQUE",
        "to_province_code": "NM",
        "to_postal_code": "87110-1046",
        "to_country_code": "US",
        "from_city": "BLAINE",
        "from_province_code": "WA",
        "from_postal_code": "98230-9997",
        "from_country_code": "US",
        "package_description": "Parcel",
        "size_description": "6 × 4 × 1.5 in",
        "weight_description": "41 g",
        "resolution": "delivery_confirmed",
        "postage_description": "Chit Chats U.S. Edge",
        "estimated_delivery_at": "2024-09-08T17:00:00.000-07:00",
        "carrier": "usps",
        "carrier_description": "usps",
        "carrier_tracking_code": "420871109214490362901402482725",
        "tracking_url": "https://chitchats.com/tracking/y2f0b87u1h",
        "ship_date": "2024-09-05",
        "resolution_description": "Delivered",
        "resolved_at": "2024-09-09T15:55:00.000-07:00",
        "tracking_events": [
        {
            "title": "Delivered, In/At Mailbox",
            "subtitle": null,
            "location_description": "ALBUQUERQUE, NM",
            "created_at": "2024-09-09T15:55:00.000-07:00",
            "status": "delivered"
        },
        {
            "title": "Out for Delivery",
            "subtitle": null,
            "location_description": "ALBUQUERQUE, NM",
            "created_at": "2024-09-09T05:10:00.000-07:00",
            "status": "out_for_delivery"
        },
        {
            "title": "In transit",
            "subtitle": "Tracking 420871109214490362901402482725",
            "location_description": null,
            "created_at": "2024-09-06T16:29:51.551-07:00",
            "status": null
        },
        {
            "title": "Departed from Chit Chats facility",
            "subtitle": null,
            "location_description": "SURREY, BC",
            "created_at": "2024-09-06T08:51:58.990-07:00",
            "status": null
        },
        {
            "title": "Arrived at Chit Chats facility",
            "subtitle": null,
            "location_description": "SURREY, BC",
            "created_at": "2024-09-05T16:39:38.732-07:00",
            "status": null
        },
        {
            "title": "Received by Chit Chats",
            "subtitle": null,
            "location_description": null,
            "created_at": "2024-09-05T16:39:38.723-07:00",
            "status": null
        },
        {
            "title": "Shipment created, Chit Chats awaiting item",
            "subtitle": null,
            "location_description": null,
            "created_at": "2024-09-05T15:35:45.665-07:00",
            "status": null
        }]
    }
}