Overview

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.

Making a request

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"

Request & Response Data

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.

Pagination

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.

Rate Limiting

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.

Testing

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.

Batches

List all batches

Returns a paginated list of batches sorted by most recently created first.

Authorizations:
APIAccessToken
query Parameters
limit
integer
Default: 100

Number of records to return per page

page
integer
Default: 1

Pagination page number

status
string
Enum: "pending" "ready" "received"

Allows for searching batches based on the status:

  • pending - Batches that have not been received
  • ready - Batches that have not been received but with all shipments ready to receive.
  • received - Batches that have been received.

Responses

Request samples

curl -s -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches"

Response samples

Content type
application/json
[]

Create a batch

Creates a new batch.

  • A successful response will contain the URL of the batch in the Location header.
Authorizations:
APIAccessToken

Responses

Request samples

curl -s -X POST \
  -H "Authorization: $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches"

Response samples

Content type
application/json
{}

Retrieve a batch

Returns the batch with the given ID.

Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the batch

Responses

Request samples

curl -s -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/1"

Response samples

Content type
application/json
{}

Delete a batch

Deletes the batch with the given ID if it is empty.

Authorizations:
APIAccessToken
path Parameters
id
required
string

Object ID of the batch

Responses

Request samples

curl -s -X DELETE \
  -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/1"

Response samples

Content type
application/json
{
  • "error": {
    }
}

Count all batches

Returns the number of batches.

Authorizations:
APIAccessToken
query Parameters
status
string
Enum: "pending" "ready" "received"

Allows for searching batches based on the status:

  • pending: Batches that have not been received
  • ready: Batches that have not been received but with all shipments ready to receive.
  • received: Batches that have been received.

Responses

Request samples

curl -s -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/count"

Response samples

Content type
application/json
{
  • "count": 110
}

Shipments

List all shipments

Returns a paginated list of shipments sorted by most recently created first.

Authorizations:
APIAccessToken
query Parameters
limit
integer
Default: 100

Number of records to return per page

page
integer
Default: 1

Pagination page number

batch_id
integer

Return shipments belonging to the given batch.

from_date
date
Example: from_date=2024-01-01

Return shipments with a created_at on or after the given date.

to_date
date
Example: to_date=2024-01-01

Return shipments with a created_at on or before the given date.

q
string

Full text searching of shipments by id, to_name, or order_id.

status
string
Enum: "canceled" "pending" "ready" "in_transit" "received" "released" "inducted" "resolved" "delivered" "exception" "voided"

Allows for searching shipments based on the status:

  • canceled - Shipment has been canceled to prevent delivery and will either be held at a branch or returned to the client.
  • pending - Shipment is in the process of being created by the client. Shipments in this state cannot be received by Chat Chats.
  • ready - Shipment is ready to be received by Chit Chats. This means the postage has been purchased or provided.
  • in_transit - Shipment is in the process of being delivered.
  • received - Shipment has been received by Chit Chats.
  • released - Chit Chats has released the shipment to the carrier.
  • inducted - Shipment is confirmed by tracking event to be in possesion by the shipping carrier.
  • resolved - Shipment has been resolved.
  • delivered - Shipment resolved as delivered.
  • exception - Shipment resolved as exception meaning that there may have been a problem delivering the shipment.
  • voided - Shipment resolved as voided because a postage refund was requested.

Responses

Request samples

curl -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments"

Response samples

Content type
application/json
[
  • {
    }
]

Create a shipment

Creates a new shipment.

  • A successful response will contain the URL of the shipment in the Location header.
Authorizations:
APIAccessToken
Request Body schema: application/json
name
required
string

Name of the recipient

address_1
required
string

Address line 1 of the recipient

address_2
string

Address line 2 of the recipient

city
required
string

City of the recipient

province_code
string

Province or state code of the recipient. 2 letter code.

postal_code
string

Postal or zip code of the recipient

country_code
required
string

Country code of the recipient. 2 letter code.

phone
string

Phone number of the recipient

email
string

Email address of the recipient

Used by final mile carriers to contact the recipient if needed. For now, only International Tracked postage provides the email to the final mile carriers.

return_name
string

Name of the return address

Only US Return Addresses can be requested for a shipment. We will use the provided address if the postage allows it, otherwise the default return address is used. Configure the default return address in your account under Settings > Returns.

return_address_1
string

Address line 1 of the return address

return_address_2
string

Address line 2 of the return address

return_city
string

City of the return address

return_province_code
string

Province or state code of the return address. 2 letter code.

return_postal_code
string

Postal or zip code of the return address

return_phone
string

Phone number of the return address

package_contents
string
Default: "merchandise"
Enum: "merchandise" "documents" "gift" "returned_goods" "sample" "other"
description
required
string

Description of the shipment. Used for customs declaration.

value
required
string

Value of the shipment

value_currency
required
string
Enum: "usd" "cad"
order_id
string

External Store Order ID

order_store
string
Enum: "adobe_commerce" "amazon" "bigcommerce" "ebay" "etsy" "shipstation" "shopify" "squarespace" "woocommerce" "other"

External Store Type

package_type
required
string
Enum: "card" "letter" "envelope" "thick_envelope" "parcel" "flat_rate_envelope" "flat_rate_legal_envelope" "flat_rate_padded_envelope" "flat_rate_gift_card_envelope" "flat_rate_window_envelope" "flat_rate_cardboard_envelope" "small_flat_rate_envelope" "small_flat_rate_box" "medium_flat_rate_box_1" "medium_flat_rate_box_2" "large_flat_rate_box"

The type of the package being shipped.

  • card - Postcard
  • letter - Letter
  • envelope - Flat Envelope
  • thick_envelope - Thick Envelope
  • parcel - Parcel
  • flat_rate_envelope - USPS Letter Flat Rate Envelope
  • flat_rate_legal_envelope - USPS Legal Flat Rate Envelope
  • flat_rate_padded_envelope - USPS Padded Flat Rate Envelope
  • flat_rate_gift_card_envelope - USPS Gift Card Flat Rate Envelope
  • flat_rate_window_envelope - USPS Window Flat Rate Envelope
  • flat_rate_cardboard_envelope - USPS Cardboard Flat Rate Envelope
  • small_flat_rate_envelope - USPS Small Flat Rate Envelope
  • small_flat_rate_box - USPS Small Flat Rate Box
  • medium_flat_rate_box_1 - USPS Medium Flat Rate Box - 1
  • medium_flat_rate_box_2 - USPS Medium Flat Rate Box - 2
  • large_flat_rate_box - USPS Large Flat Rate Box
weight_unit
required
string
Enum: "g" "kg" "oz" "lb"
weight
required
number

Weight of the shipment

size_unit
required
string
Enum: "cm" "m" "in"
size_x
required
number

Length of the shipment

size_y
required
number

Width of the shipment

size_z
required
number

Height of the shipment

insurance_requested
boolean

Request insurance for the shipment

signature_requested
boolean

Request signature confirmation for the shipment

vat_reference
string

VAT reference number. Tax identification number.

duties_paid_requested
boolean

Request duties paid postage for the shipment.

Only available for chit_chats_international_tracked postage type.

vat_reference must be provided in order to use duties paid postages.

postage_type
string

Refer to the postage_type value returned by the rates array in the shipment details.

Some possible values:

  • unknown - Use when you wish to view rates before buying postage
  • chit_chats_us_edge - Chit Chats U.S. Edge
  • chit_chats_us_select - Chit Chats U.S. Select
  • chit_chats_us_slim - Chit Chats U.S. Slim
  • usps_express - USPS Priority Mail Express®
  • usps_first - USPS First-Class Mail®
  • usps_ground_advantage - USPS Ground Advantage®
  • usps_library_mail - USPS Library Mail
  • usps_media_mail - USPS Media Mail®
  • usps_priority - USPS Priority Mail®
  • usps_other - USPS Other Mail Class
  • chit_chats_canada_tracked - Chit Chats Canada Tracked
  • chit_chats_select - Chit Chats Select
  • chit_chats_slim - Chit Chats Slim
  • chit_chats_international_tracked - Chit Chats International Tracked
  • usps_express_mail_international - USPS Priority Mail Express International®
  • usps_first_class_mail_international - USPS First-Class Mail International
  • usps_first_class_package_international_service - USPS First-Class Package International Service®
  • usps_priority_mail_international - USPS Priority Mail International®
cheapest_postage_type_requested
string
Value: "yes"

Selects the cheapest available rate for a shipment.

postage_type must be unknown.

Can be customized in your account under Settings > Cheapest Postage Type Option

tracking_number
string

Tracking number of the shipment

ship_date
string

This is the date Chit Chats is expected to receive your shipment.

Accepted values are today or a date in the format of YYYY-MM-DD

Array of objects

Required for international shipments (non US & CA).

Line items for the shipment.

Responses

Request samples

Content type
application/json
{
  • "name": "Jane Doe",
  • "address_1": "123 ANYWHERE ST.",
  • "address_2": "",
  • "city": "Vancouver",
  • "province_code": "BC",
  • "postal_code": "V6K 1A1",
  • "country_code": "CA",
  • "phone": "800-555-1212",
  • "package_contents": "merchandise",
  • "description": "Hand made bracelet",
  • "value": "84.99",
  • "value_currency": "usd",
  • "order_id": "",
  • "order_store": "",
  • "package_type": "parcel",
  • "weight_unit": "g",
  • "weight": 250,
  • "size_unit": "cm",
  • "size_x": 10,
  • "size_y": 5,
  • "size_z": 2,
  • "insurance_requested": true,
  • "signature_requested": false,
  • "vat_reference": "",
  • "duties_paid_requested": false,
  • "postage_type": "chit_chats_canada_tracked",
  • "cheapest_postage_type_requested": "no",
  • "tracking_number": "",
  • "ship_date": "today",
  • "line_items": [
    ]
}

Response samples

Content type
application/json
{
  • "shipment": {
    }
}

Retrieve a shipment

Returns the shipment with the given ID.

Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the shipment

Responses

Request samples

curl -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/1by4s9h87b"

Response samples

Content type
application/json
{
  • "shipment": {
    }
}

Delete a shipment

Deletes a shipment if allowed.

If the shipment has purchased postage or has been received by Chit Chats the shipment cannot be deleted but it can be refunded to void the shipment.

Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the shipment

Responses

Request samples

curl -s -X DELETE \
  -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/abcde12345"

Response samples

Content type
application/json
{
  • "error": {
    }
}

Count all shipments

Returns the number of shipments.

Authorizations:
APIAccessToken
query Parameters
status
string
Enum: "canceled" "pending" "ready" "in_transit" "received" "released" "inducted" "resolved" "delivered" "exception" "voided"

Allows for searching shipments based on the status:

  • canceled - Shipment has been canceled to prevent delivery and will either be held at a branch or returned to the client.
  • pending - Shipment is in the process of being created by the client. Shipments in this state cannot be received by Chat Chats.
  • ready - Shipment is ready to be received by Chit Chats. This means the postage has been purchased or provided.
  • in_transit - Shipment is in the process of being delivered.
  • received - Shipment has been received by Chit Chats.
  • released - Chit Chats has released the shipment to the carrier.
  • inducted - Shipment is confirmed by tracking event to be in possesion by the shipping carrier.
  • resolved - Shipment has been resolved.
  • delivered - Shipment resolved as delivered.
  • exception - Shipment resolved as exception meaning that there may have been a problem delivering the shipment.
  • voided - Shipment resolved as voided because a postage refund was requested.

Responses

Request samples

curl -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/count"

Response samples

Content type
application/json
{
  • "count": 100
}

Refresh a shipment

Refreshes the postage rates for the shipment

Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the shipment

Request Body schema: application/json
insurance_requested
boolean

Request insurance for the shipment

media_mail_requested
boolean

Request media mail for the shipment

signature_requested
boolean

Request signature confirmation for the shipment

ship_date
string

This is the date Chit Chats is expected to receive your shipment.

Accepted values are today or a date in the format of YYYY-MM-DD

Responses

Request samples

Content type
application/json
{
  • "insurance_requested": true,
  • "media_mail_requested": false,
  • "signature_requested": false,
  • "ship_date": "today"
}

Response samples

Content type
application/json
{
  • "shipment": {
    }
}

Buy a shipment

Attempt to buy the selected postage for the given shipment. A successful result only means that a purchase is requested. The status of the shipment may be postage_requested. If this happens the caller will need to wait a few seconds and poll until the shipment returns ready or postage_purchase_failed.

The reason for not blocking is that buying postage can take a few seconds (exact duration is dependent on our postage providers but this will normally complete in less than 3 seconds). Because of the delay waiting to return for each call, is inefficient when buying 1000s of shipments. In this case, we recommend calling the buy endpoint on all your shipments and then poll at reasonable intervals until the shipment's status changes to ready. The example below shows how to accomplish this.

  def buy
    patch(:buy)

    # Buying postage can take a few seconds to process and generate a label
    # so block and poll until we know it doesn't fail.
    sleep(0.5) while shipment.status == "postage_requested"
    raise "Purchase postage failed" if shipment.status == "postage_purchase_failed"

    shipment
  end
Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the shipment

Request Body schema: application/json
postage_type
string

Refer to the postage_types values returned by the rates array in the shipment details.

Responses

Request samples

Content type
application/json
{
  • "postage_type": "chit_chats_canada_tracked"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Refund a shipment

Requests refund for the given shipment. Some postage types may take up to 2 weeks to process. Poll shipment to check refund status.

Authorizations:
APIAccessToken
path Parameters
id
required
string

ID of the shipment

Responses

Request samples

curl -s -X PATCH \
  -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/abcde12345/refund"

Response samples

Content type
application/json
{
  • "error": {
    }
}

Add to batch

Adds the given shipments to the given batch.

Authorizations:
APIAccessToken
Request Body schema: application/json
batch_id
required
integer

ID of the batch

shipment_ids
required
Array of strings

Shipment IDs to add to the batch

Responses

Request samples

Content type
application/json
{
  • "batch_id": 1,
  • "shipment_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Remove from batch

Removes shipments from belonging to a batch.

Authorizations:
APIAccessToken
Request Body schema: application/json
shipment_ids
required
Array of strings

Shipment IDs to remove from the batches

Responses

Request samples

Content type
application/json
{
  • "shipment_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Returns

List all returns

Returns a paginated list of returns sorted by most recently created first.

Authorizations:
APIAccessToken
query Parameters
limit
integer
Default: 100

Number of records to return per page

page
integer
Default: 1

Pagination page number

status
string
Enum: "on_hold" "in_transit" "ready" "resolved"

Allows for searching returns based on the status:

  • on_hold - Return has been received by Chit Chats, but no return method has been specified by the client.
  • in_transit - Return has been received by Chit Chats and is being processed.
  • ready - Return is ready to be picked up at client's preferred branch.
  • resolved - Return has been resolved.
reason
string
Enum: "unknown" "unclaimed" "incomplete_address" "damaged" "other"

Allows for searching returns based on the reason for return:

  • unknown - Reason not known or not specified.
  • unclaimed - Shipment was not claimed by the recipient.
  • incomplete_address - Shipment could not be delivered due to incomplete or invalid address.
  • damaged - Shipment was damaged.
  • other - Other reason for return.

Responses

Request samples

curl -H "Authorization: $ACCESS_TOKEN" \
  "https://chitchats.com/api/v1/clients/$CLIENT_ID/returns"

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tracking

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