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.
Returns a paginated list of batches sorted by most recently created first.
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:
|
curl -s -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches"
[- {
- "id": 562,
- "status": "pending",
- "created_at": "2024-09-11T09:33:48.926-07:00",
}, - {
- "id": 560,
- "status": "pending",
- "created_at": "2024-08-14T11:07:30.290-07:00",
}
]
Creates a new batch.
Location
header.curl -s -X POST \ -H "Authorization: $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches"
{- "batch": {
- "id": 563,
- "status": "pending",
- "created_at": "2024-09-11T15:05:56.932-07:00",
}
}
Returns the batch with the given ID.
id required | string ID of the batch |
curl -s -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/1"
{- "batch": {
- "id": 563,
- "status": "pending",
- "created_at": "2024-09-11T15:05:56.932-07:00",
}
}
Deletes the batch with the given ID if it is empty.
id required | string Object ID of the batch |
curl -s -X DELETE \ -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/1"
{- "error": {
- "message": "Unauthorized"
}
}
Returns the number of batches.
status | string Enum: "pending" "ready" "received" Allows for searching batches based on the status:
|
curl -s -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/batches/count"
{- "count": 110
}
Returns a paginated list of shipments sorted by most recently created first.
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 |
status | string Enum: "canceled" "pending" "ready" "in_transit" "received" "released" "inducted" "resolved" "delivered" "exception" "voided" Allows for searching shipments based on the status:
|
curl -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments"
[- {
- "id": "I58U3Z22C7",
- "status": "ready",
- "batch_id": null,
- "to_name": "Jane Doe",
- "to_address_1": "3810 JACOMBS RD",
- "to_address_2": null,
- "to_city": "RICHMOND",
- "to_province_code": "BC",
- "to_postal_code": "V6V 1Y6",
- "to_country_code": "CA",
- "to_phone": "5555555555",
- "to_email": null,
- "return_name": "123456 John Doe",
- "return_address_1": "109-3860 JACOMBS ROAD",
- "return_address_2": null,
- "return_city": "RICHMOND",
- "return_province_code": "BC",
- "return_postal_code": "V6V 1Y6",
- "return_country_code": "CA",
- "return_phone": "1-555-555-5555",
- "is_return_dispose": false,
- "package_contents": "merchandise",
- "description": "1 Men's T-shirt",
- "value": "193.53",
- "value_currency": "CAD",
- "order_id": "16649",
- "order_store": null,
- "package_type": "thick_envelope",
- "size_unit": "in",
- "size_x": 12,
- "size_y": 6,
- "size_z": 1,
- "weight_unit": "oz",
- "weight": 4.1,
- "is_insured": true,
- "is_insurance_requested": true,
- "is_media_mail_requested": false,
- "is_signature_requested": false,
- "is_delivery_duties_paid_requested": false,
- "postage_type": "chit_chats_select",
- "carrier": "intelcom",
- "carrier_tracking_code": "CCI58U3Z22C7",
- "ship_date": "2024-09-13",
- "purchase_amount": "9.68",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "created_at": "2024-09-12T21:25:36.757-07:00",
- "rates": [
- {
- "postage_type": "chit_chats_select",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Select",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "7.20",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "9.68"
}, - {
- "postage_type": "chit_chats_canada_tracked",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Canada Tracked",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "12.56",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.60",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "12.56",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "15.04"
}
]
}
]
Creates a new shipment.
Location
header.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 |
string Email address of the recipient Used by final mile carriers to contact the recipient if needed.
For now, only | |
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.
|
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
|
postage_type | string Refer to the Some possible values:
|
cheapest_postage_type_requested | string Value: "yes" Selects the cheapest available rate for a shipment.
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 |
Array of objects Required for international shipments (non US & CA). Line items for the shipment. |
{- "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": [
- {
- "quantity": 1,
- "description": "Hand made bracelet",
- "value_amount": "84.49",
- "currency_code": "usd",
- "hs_tariff_code": null,
- "origin_country": null
}
]
}
{- "shipment": {
- "id": "R4Q286T84T",
- "status": "unpaid",
- "batch_id": null,
- "to_name": "John Doe",
- "to_address_1": "3810 JACOMBS RD",
- "to_address_2": null,
- "to_city": "RICHMOND",
- "to_province_code": "BC",
- "to_postal_code": "V6V 1Y6",
- "to_country_code": "CA",
- "to_phone": "5555555555",
- "to_email": null,
- "return_name": null,
- "return_address_1": null,
- "return_address_2": null,
- "return_city": null,
- "return_province_code": null,
- "return_postal_code": null,
- "return_country_code": null,
- "return_phone": null,
- "is_return_dispose": false,
- "package_contents": "merchandise",
- "description": "1 Men's T-Shirt",
- "value": "193.53",
- "value_currency": "CAD",
- "order_id": "16649",
- "order_store": null,
- "package_type": "thick_envelope",
- "size_unit": "in",
- "size_x": 12,
- "size_y": 6,
- "size_z": 1,
- "weight_unit": "oz",
- "weight": 4.1,
- "is_insured": true,
- "is_insurance_requested": true,
- "is_media_mail_requested": false,
- "is_signature_requested": false,
- "is_delivery_duties_paid_requested": false,
- "postage_type": "chit_chats_select",
- "carrier": "unknown",
- "carrier_tracking_code": null,
- "ship_date": "2024-09-13",
- "purchase_amount": "9.68",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "created_at": "2024-09-12T21:51:42.330-07:00",
- "postage_label_png_url": null,
- "postage_label_zpl_url": null,
- "rates": [
- {
- "postage_type": "chit_chats_select",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Select",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "7.20",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "9.68"
}, - {
- "postage_type": "chit_chats_canada_tracked",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Canada Tracked",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "12.56",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.60",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "12.56",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "15.04"
}
], - "tracking_events": [
- {
- "type": "create_shipment",
- "title": "Shipment created, Chit Chats awaiting item",
- "subtitle": null,
- "location_description": null,
- "created_at": "2024-09-12T21:51:42.363-07:00",
- "status": null
}
]
}
}
Returns the shipment with the given ID.
id required | string ID of the shipment |
curl -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/1by4s9h87b"
{- "shipment": {
- "id": "R4Q286T84T",
- "status": "unpaid",
- "batch_id": null,
- "to_name": "John Doe",
- "to_address_1": "3810 JACOMBS RD",
- "to_address_2": null,
- "to_city": "RICHMOND",
- "to_province_code": "BC",
- "to_postal_code": "V6V 1Y6",
- "to_country_code": "CA",
- "to_phone": "5555555555",
- "to_email": null,
- "return_name": null,
- "return_address_1": null,
- "return_address_2": null,
- "return_city": null,
- "return_province_code": null,
- "return_postal_code": null,
- "return_country_code": null,
- "return_phone": null,
- "is_return_dispose": false,
- "package_contents": "merchandise",
- "description": "1 Men's T-Shirt",
- "value": "193.53",
- "value_currency": "CAD",
- "order_id": "16649",
- "order_store": null,
- "package_type": "thick_envelope",
- "size_unit": "in",
- "size_x": 12,
- "size_y": 6,
- "size_z": 1,
- "weight_unit": "oz",
- "weight": 4.1,
- "is_insured": true,
- "is_insurance_requested": true,
- "is_media_mail_requested": false,
- "is_signature_requested": false,
- "is_delivery_duties_paid_requested": false,
- "postage_type": "chit_chats_select",
- "carrier": "unknown",
- "carrier_tracking_code": null,
- "ship_date": "2024-09-13",
- "purchase_amount": "9.68",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "created_at": "2024-09-12T21:51:42.330-07:00",
- "postage_label_png_url": null,
- "postage_label_zpl_url": null,
- "rates": [
- {
- "postage_type": "chit_chats_select",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Select",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "7.20",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "9.68"
}, - {
- "postage_type": "chit_chats_canada_tracked",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Canada Tracked",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "12.56",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.60",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "12.56",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "15.04"
}
], - "tracking_events": [
- {
- "type": "create_shipment",
- "title": "Shipment created, Chit Chats awaiting item",
- "subtitle": null,
- "location_description": null,
- "created_at": "2024-09-12T21:51:42.363-07:00",
- "status": null
}
]
}
}
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.
id required | string ID of the shipment |
curl -s -X DELETE \ -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/abcde12345"
{- "error": {
- "message": "Unauthorized"
}
}
Returns the number of shipments.
status | string Enum: "canceled" "pending" "ready" "in_transit" "received" "released" "inducted" "resolved" "delivered" "exception" "voided" Allows for searching shipments based on the status:
|
curl -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/count"
{- "count": 100
}
Refreshes the postage rates for the shipment
id required | string ID of the shipment |
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 |
{- "insurance_requested": true,
- "media_mail_requested": false,
- "signature_requested": false,
- "ship_date": "today"
}
{- "shipment": {
- "id": "R4Q286T84T",
- "status": "unpaid",
- "batch_id": null,
- "to_name": "John Doe",
- "to_address_1": "3810 JACOMBS RD",
- "to_address_2": null,
- "to_city": "RICHMOND",
- "to_province_code": "BC",
- "to_postal_code": "V6V 1Y6",
- "to_country_code": "CA",
- "to_phone": "5555555555",
- "to_email": null,
- "return_name": null,
- "return_address_1": null,
- "return_address_2": null,
- "return_city": null,
- "return_province_code": null,
- "return_postal_code": null,
- "return_country_code": null,
- "return_phone": null,
- "is_return_dispose": false,
- "package_contents": "merchandise",
- "description": "1 Men's T-Shirt",
- "value": "193.53",
- "value_currency": "CAD",
- "order_id": "16649",
- "order_store": null,
- "package_type": "thick_envelope",
- "size_unit": "in",
- "size_x": 12,
- "size_y": 6,
- "size_z": 1,
- "weight_unit": "oz",
- "weight": 4.1,
- "is_insured": true,
- "is_insurance_requested": true,
- "is_media_mail_requested": false,
- "is_signature_requested": false,
- "is_delivery_duties_paid_requested": false,
- "postage_type": "chit_chats_select",
- "carrier": "unknown",
- "carrier_tracking_code": null,
- "ship_date": "2024-09-13",
- "purchase_amount": "9.68",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "created_at": "2024-09-12T21:51:42.330-07:00",
- "postage_label_png_url": null,
- "postage_label_zpl_url": null,
- "rates": [
- {
- "postage_type": "chit_chats_select",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Select",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "7.20",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.34",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "7.20",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "9.68"
}, - {
- "postage_type": "chit_chats_canada_tracked",
- "postage_carrier_type": "chit_chats",
- "postage_description": "Chit Chats Canada Tracked",
- "signature_confirmation_description": null,
- "delivery_duties_paid_description": null,
- "delivery_time_description": "Estimated delivery in 8 business days",
- "tracking_type_description": "Full tracking included",
- "is_insured": true,
- "purchase_amount": "12.56",
- "provincial_tax": null,
- "provincial_tax_label": null,
- "federal_tax": "0.60",
- "federal_tax_label": "GST (5%)",
- "postage_fee": "12.56",
- "insurance_fee": "2.48",
- "delivery_fee": null,
- "payment_amount": "15.04"
}
], - "tracking_events": [
- {
- "type": "create_shipment",
- "title": "Shipment created, Chit Chats awaiting item",
- "subtitle": null,
- "location_description": null,
- "created_at": "2024-09-12T21:51:42.363-07:00",
- "status": null
}
]
}
}
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
id required | string ID of the shipment |
postage_type | string Refer to the postage_types values returned by the |
{- "postage_type": "chit_chats_canada_tracked"
}
{- "error": {
- "message": "Error message"
}
}
Requests refund for the given shipment. Some postage types may take up to 2 weeks to process. Poll shipment to check refund status.
id required | string ID of the shipment |
curl -s -X PATCH \ -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/shipments/abcde12345/refund"
{- "error": {
- "message": "Error message"
}
}
Adds the given shipments to the given batch.
batch_id required | integer ID of the batch |
shipment_ids required | Array of strings Shipment IDs to add to the batch |
{- "batch_id": 1,
- "shipment_ids": [
- "ABCDE12345",
- "Q5P4R3S2T1"
]
}
{- "error": {
- "message": "Unauthorized"
}
}
Removes shipments from belonging to a batch.
shipment_ids required | Array of strings Shipment IDs to remove from the batches |
{- "shipment_ids": [
- "ABCDE12345",
- "Q5P4R3S2T1"
]
}
{- "error": {
- "message": "Unauthorized"
}
}
Returns a paginated list of returns sorted by most recently created first.
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:
|
reason | string Enum: "unknown" "unclaimed" "incomplete_address" "damaged" "other" Allows for searching returns based on the reason for return:
|
curl -H "Authorization: $ACCESS_TOKEN" \ "https://chitchats.com/api/v1/clients/$CLIENT_ID/returns"
[- {
- "id": "B0V7D2P602",
- "status": "returned",
- "created_at": "2024-07-08T16:08:32.760-07:00",
- "updated_at": "2024-07-08T16:39:21.883-07:00",
- "resolution": "delivery_confirmed",
- "resolved_at": "2024-07-08T16:39:21.864-07:00",
- "return_reason": "damaged",
- "return_reason_note": "Box torn open",
- "original_shipment": {
- "id": "F6U7A7M6D0",
- "order_type": "other",
- "order_reference": null,
- "to_name": "chit chats us edge",
- "to_street": "21000 HACIENDA BLVD",
- "to_street_2": "BUILDING B APARTMENT G06",
- "to_city": "CALIFORNIA CITY",
- "to_province_code": "CA",
- "to_postal_code": "93505",
- "to_country_code": "US",
- "to_phone": null,
- "customs_description": "1 5 USB cables",
- "created_at": "2024-06-06T13:57:02.611-07:00",
- "updated_at": "2024-06-06T22:41:00.240-07:00",
- "resolution": "unknown",
- "resolved_at": null
}
}, - {
- "id": "Q8D0N7T4M9",
- "status": "returned",
- "created_at": "2024-07-08T14:16:54.106-07:00",
- "updated_at": "2024-07-08T15:48:16.549-07:00",
- "resolution": "delivery_confirmed",
- "resolved_at": "2024-07-08T15:48:16.538-07:00",
- "return_reason": "unknown",
- "return_reason_note": null,
- "original_shipment": {
- "id": "V8A02M8Z63",
- "order_type": "other",
- "order_reference": null,
- "to_name": "chit chats us edge",
- "to_street": "21000 HACIENDA BLVD",
- "to_street_2": "BUILDING B APARTMENT G06",
- "to_city": "CALIFORNIA CITY",
- "to_province_code": "CA",
- "to_postal_code": "93505",
- "to_country_code": "US",
- "to_phone": null,
- "customs_description": "1 5 USB cables",
- "created_at": "2024-06-07T11:06:33.272-07:00",
- "updated_at": "2024-06-07T11:07:17.613-07:00",
- "resolution": "unknown",
- "resolved_at": null
}
}
]
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
}]
}
}