{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c693e881-c819-4c67-b895-6e408cd8a8e6","name":"commerceship-api","description":"Welcome to CommerceShip! Our platform is designed to transform  \nyour shipping and logistics operations, offering seamless integration  \nfor e-commerce shippers, logistics providers, and businesses of all sizes.  \nWith CommerceShip API, you gain access to a range of powerful tools and  \nservices, including real-time shipping rate comparisons, label  \ncreation, efficient tracking systems, and more. Our API is built for  \nease of use and flexibility, ensuring that you can customize it to meet  \nyour unique business needs.\n\n# Getting Started with CommerceShip API\n\nThis guide will walk you through the essential steps to begin using the CommerceShip API for your shipping and logistics operations.\n\n## 1\\. Sign Up for an Account\n\nTo start using CommerceShip, you'll need to create an account:\n\n- Visit [https://app.commerceship.com/account/register](https://app.commerceship.com/account/register)\n    \n\nDuring registration, you'll be asked to provide basic information about your business and create your login credentials.\n\n## 2\\. Select a Billing Plan\n\nCommerceShip offers several billing plans designed to fit businesses of different sizes and shipping volumes:\n\n- Review the available plans at [https://www.commerceship.com/pricing.html](https://www.commerceship.com/pricing.html)\n    \n- Consider your monthly shipping volume and required features when selecting a plan\n    \n- You can start with a lower tier and upgrade as your shipping needs grow\n    \n\n## 3\\. Download API Documentation in Postman\n\nOur API documentation is available as a Postman collection, making it easy to explore and test the API:\n\n1. Download and install [Postman](https://www.postman.com/downloads/) if you haven't already\n    \n2. Download the CommerceShip Postman collection from our developer portal\n    \n3. Import the collection into Postman: Click \"Import\" in Postman and select the downloaded file\n    \n4. Set up your environment variables with your API endpoints\n    \n\n## 4\\. Authenticate and Get JWT Token\n\nAll API requests require authentication using a JWT token. To obtain your token:\n\n1. Use the login endpoint with your account credentials\n    \n2. Store the JWT token returned in both the header and body\n    \n3. Include this token in all subsequent API requests using the Authorization header\n    \n4. Note that JWT tokens expire hourly and will need to be refreshed\n    \n\n## 5\\. Next Steps\n\nOnce authenticated, you can request shipping rates, create orders and create shipments and manifests. You can also explore other API features like:\n\n- Work with order batches\n    \n- Address validation\n    \n- Managing return labels\n    \n- Tracking shipments\n    \n- Integrating with your e-commerce platform\n    \n\nFor more details on these advanced features, consult the complete API documentation or contact our support team.\n\n# API Workflows\n\nCommerceShip API offers two distinct workflows to accommodate different business needs and integration scenarios. Each approach has specific advantages depending on your implementation requirements.\n\n## Two-Step \"Complex\" Process\n\nThis workflow separates order creation from label generation, offering greater flexibility and control:\n\n1. **Create an Order**:\n    \n    - An order can be as complete or incomplete as your available data permits\n        \n    - At minimum, you need origin and destination postal codes (with country codes for international shipments)\n        \n    - Orders can be updated at any point to add missing information\n        \n    - This approach allows for phased data collection in your application flow\n        \n2. **Get Shipping Rates**:\n    \n    - Once an order has basic address information, you can retrieve available carrier rates\n        \n    - This step allows you to present shipping options to your customers\n        \n    - Rates can be recalculated if order details change\n        \n3. **Generate Shipment and Label**:\n    \n    - When ready to ship, convert the order to a shipment\n        \n    - This step requires complete origin and destination addresses, package weight, and selected carrier service\n        \n    - A shipping label URL is returned, which can be accessed to print the label\n        \n\nThis workflow is ideal for e-commerce platforms where shipping options need to be presented before order completion, or when order data is collected across multiple steps.\n\n## One-Step \"Direct\" Process\n\nFor scenarios requiring immediate label generation, the API offers a streamlined approach:\n\n1. **Create Label Directly**:\n    \n    - Complete shipping information is provided in a single API call\n        \n    - Required data includes complete origin and destination addresses, package weight, and carrier service\n        \n    - The order and shipment are created simultaneously\n        \n    - A shipping label URL is returned immediately\n        \n\nThis approach prioritizes performance and simplicity, making it ideal for:\n\n- Back-office shipping operations\n    \n- Integration with warehouse management systems\n    \n- Scenarios where all shipping data is available upfront\n    \n\n# **Signup**\n\n[https://app.commerceship.com/account/register](https://app.commerceship.com/account/register)\n\n# **API Endpoints**\n\n[https://api.commerceship.com](https://api.commerceship.com)\n\n# **Authentication**\n\nTo ensure secure access to CommerceShip API, we use JWT (JSON Web Token) authentication. This JWT-based authentication system provides a secure and streamlined way to interact with CommerceShip API, safeguarding your data and operations.\n\n1. Generate JWT Token: Once registered, generate your JWT token by calling login: {{url}}/v1/users/login. The header and body responses will both contain the JWT token.\n    \n2. Include JWT Token in API Requests: For every API call, include this JWT token in the request header using the standard format: Authorization: Bearer \\[Your JWT Token\\].\n    \n3. JWT tokens will expire every hour. You will need to regenerate them by calling login when they expire.\n    \n\nAuthentication can be performed by API key as well. You can create API keys by logging into your account and navigating to Account -> API Keys. The API keys are passed into the request with key \"X-Api-Key\".\n\n**MCP endpoints require API Key authentication (JWT is not supported for MCP).**\n\n1. Create an API key in the CommerceShip app:  \n    **Account → API Keys**\n    \n2. Send your API key in every MCP request:\n    \n\n**Header**\n\n- `X-Api-Key: YOUR_API_KEY`\n    \n\n## MCP (AI Analytics & Optimization API)\n\nCommerceShip MCP endpoints are **AI-friendly analytics and optimization endpoints** designed for building copilots, dashboards, automated reports, and “what‑if” simulations on top of your CommerceShip shipment data.\n\nThese endpoints power the same KPI, tracking health, and optimization workflows used by CommerceShip’s internal AI features—now available to all developers as a public API.\n\n### What you can build with MCP\n\n- **Executive dashboards**: spend, shipment volume, averages, breakdowns by carrier/service/zone, surcharges\n    \n- **Tracking health monitoring**: on‑time vs late mix, exceptions, missing tracking, delivery status counts\n    \n- **Operational optimization**: baseline vs optimized ground/air mix, carrier mix, network changes\n    \n- **Financial what‑if scenarios**: “What would this traffic cost on Carrier X using rate type Y?”\n    \n\n# **Errors**\n\nError response example:\n\n`{ \"errors\": [ { \"type\": \"validation\", \"message\": \"email: is already taken\" }, { \"type\": \"validation\", \"message\": \"password: must be at least 8 characters long, must be at least 1 character uppercase, must be at least 1 character lowercase, must be at least 1 special character\" } ] }`\n\n# **Pagination**\n\nAll endpoints that return collections or lists of elements use pagination to manage response size and improve performance. To navigate through paginated results, use the `page` and `page_size` query parameters (e.g., `/v1/shipments?page=2&page_size=25`). By default, if not specified, `page=0` and `page_size=50`. The maximum allowed `page_size` is 200. Response headers provide essential pagination metadata: `page` (current page), `page_size` (number of items per page), `total_pages` (total available pages), and `total_items` (total number of items across all pages). To navigate through results, simply increment the page parameter until you reach `total-pages`.\n\n# Idempotency\n\nOrder idempotency is user-scoped in Orders. A re-played order that was already generated as a resource on the server, will result in a read operation vs a create operation. The idempotency is built in this priority order:\n\n1. externalOrderId (normalized)\n    \n2. A derived shipto fingerprint: shipDate + destination name + street1 + city + state + postalCode (all normalized)\n    \n3. Optional fallback to orderNumber (only when fallback is enabled)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"24641535","team":5884506,"collectionId":"c693e881-c819-4c67-b895-6e408cd8a8e6","publishedId":"2s9YkgE5eg","public":true,"publicUrl":"https://docs.commerceship.com","privateUrl":"https://go.postman.co/documentation/24641535-c693e881-c819-4c67-b895-6e408cd8a8e6","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0a0126"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/ec132826-723e-4abf-b775-5d775a66ee6b/Y29tbWVyY2VzaGlwLWxvZ28tY3lhbi1vdy1vbmUtbGluZS5wbmc=","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"0a0126"}},{"name":"light","logo":"https://content.pstmn.io/ec132826-723e-4abf-b775-5d775a66ee6b/Y29tbWVyY2VzaGlwLWxvZ28tY3lhbi1vdy1vbmUtbGluZS5wbmc=","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0a0126"}}]}},"version":"8.10.1","publishDate":"2023-12-11T23:46:53.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/ec132826-723e-4abf-b775-5d775a66ee6b/Y29tbWVyY2VzaGlwLWxvZ28tY3lhbi1vdy1vbmUtbGluZS5wbmc=","logoDark":"https://content.pstmn.io/ec132826-723e-4abf-b775-5d775a66ee6b/Y29tbWVyY2VzaGlwLWxvZ28tY3lhbi1vdy1vbmUtbGluZS5wbmc="}},"statusCode":200},"environments":[{"name":"production","id":"a3a4ea4f-a652-4560-ac15-e3ff30e07be7","owner":"24641535","values":[{"key":"url","value":"https://api.commerceship.com","enabled":true,"type":"default"},{"key":"default_from_address","value":"{\n    \"first_name\" : \"Theodore\",\n    \"last_name\" : \"Roberts\",\n    \"email\" : \"theo.rob5@gmail.com\",\n    \"street1\" : \"1 Dr Carlton B Goodlett Pl\",\n    \"city_locality\" : \"San Francisco\",\n    \"state_province\" : \"CA\",\n    \"postal_code\" : \"94102\",\n    \"country_code\" : \"US\"\n}","enabled":true,"type":"default"},{"key":"return_label","value":"true","enabled":true,"type":"default"},{"key":"image_type","value":"png","enabled":true,"type":"default"},{"key":"to_address_z1","value":"{\n    \"first_name\" : \"Elizabeth\",\n    \"last_name\" : \"Johnson\",\n    \"street1\" : \"1011 Market St\",\n    \"city_locality\" : \"San Francisco\",\n    \"state_province\" : \"CA\",\n    \"postal_code\" : \"94103\",\n    \"country_code\" : \"US\"\n}\n","enabled":true,"type":"default"},{"key":"to_address_z2","value":"{\n    \"first_name\" : \"John\",\n    \"last_name\" : \"Doe\",\n    \"street1\" : \"915 I St\",\n    \"city_locality\" : \"Sacramento\",\n    \"state_province\" : \"CA\",\n    \"postal_code\" : \"95814\",\n    \"country_code\" : \"US\"\n}\n","enabled":true,"type":"default"},{"key":"to_address_z3","value":"{\n    \"first_name\" : \"Oliver\",\n    \"last_name\" : \"Jackson\",\n    \"street1\" : \"1 E 1st St\",\n    \"city_locality\" : \"Reno\",\n    \"state_province\" : \"NV\",\n    \"postal_code\" : \"89501\",\n    \"country_code\" : \"US\"\n}\n\n","enabled":true,"type":"default"},{"key":"to_address_z4","value":"{\n    \"first_name\" : \"Sophia\",\n    \"last_name\" : \"Martinez\",\n    \"street1\" : \"571 Idaho St\",\n    \"city_locality\" : \"Elko\",\n    \"state_province\" : \"NV\",\n    \"postal_code\" : \"89801\",\n    \"country_code\" : \"US\"\n}\n\n","enabled":true,"type":"default"},{"key":"to_address_z5","value":"{\n    \"first_name\" : \"Alice\",\n    \"last_name\" : \"Miller\",\n    \"street1\" : \"1437 Bannock St\",\n    \"city_locality\" : \"Denver\",\n    \"state_province\" : \"CO\",\n    \"postal_code\" : \"80202\",\n    \"country_code\" : \"US\"\n}\n","enabled":true,"type":"default"},{"key":"to_address_z6","value":"{\n    \"first_name\" : \"Emily\",\n    \"last_name\" : \"Smith\",\n    \"street1\" : \"200 N Walker Ave\",\n    \"city_locality\" : \"Oklahoma City\",\n    \"state_province\" : \"OK\",\n    \"postal_code\" : \"73102\",\n    \"country_code\" : \"US\"\n}\n\n","enabled":true,"type":"default"},{"key":"to_address_z7","value":"{\n    \"first_name\" : \"Kyle\",\n    \"last_name\" : \"Meyer\",\n    \"street1\" : \"1102 Lohmans Crossing Rd\",\n    \"city_locality\" : \"Lakeway\",\n    \"state_province\" : \"TX\",\n    \"postal_code\" : \"78738\",\n    \"country_code\" : \"US\"\n}","enabled":true,"type":"default"},{"key":"to_address_z8","value":"{\n    \"first_name\" : \"Charlie\",\n    \"last_name\" : \"Taylor\",\n    \"street1\" : \"3500 Pan American Dr\",\n    \"city_locality\" : \"Miami\",\n    \"state_province\" : \"FL\",\n    \"postal_code\" : \"33133\",\n    \"country_code\" : \"US\"\n}\n","enabled":true,"type":"default"},{"key":"to_address_z9","value":"{\n\"first_name\": \"Theodore\",\n\"last_name\": \"Roberts\",\n\"street1\": \"251 N. CHALAN ANTIGO STREET\",\n\"city_locality\": \"Talofofo\",\n\"state_province\": \"GU\",\n\"postal_code\": \"96915\",\n\"country_code\": \"US\"\n}","enabled":true,"type":"default"},{"key":"intl_address_CA","value":"{\n    \"first_name\" : \"John\",\n    \"last_name\" : \"Doe\",\n    \"street1\" : \"55 Eglinton Ave E\",\n    \"city_locality\" : \"Toronto\",\n    \"state_province\" : \"ON\",\n    \"postal_code\" : \"M4P 1G8\",\n    \"country_code\" : \"CA\"\n}\n","enabled":true,"type":"default"},{"key":"intl_address_RO","value":"{\n    \"first_name\" : \"Ion\",\n    \"last_name\" : \"Popescu\",\n    \"street1\" : \"Strada George Enescu 12\",\n    \"city_locality\" : \"Bucharest\",\n    \"state_province\" : \"Bucharest\",\n    \"postal_code\" : \"010301\",\n    \"country_code\" : \"RO\"\n}\n","enabled":true,"type":"default"},{"key":"intl_address_PA","value":"{\n    \"first_name\" : \"Juan\",\n    \"last_name\" : \"Perez\",\n    \"street1\" : \"Avenida Balboa 1000\",\n    \"city_locality\" : \"Panama City\",\n    \"state_province\" : \"Panama\",\n    \"postal_code\" : \"0816-00507\",\n    \"country_code\" : \"PA\"\n}\n","enabled":true,"type":"default"},{"key":"rateSetIdToray2024","value":"35773f29-15da-4e18-a0d2-f8ea8ceef5d3","enabled":true,"type":"default"},{"key":"rateSetIdToray2020","value":"4499abdf-519e-4156-b66b-fef9f53589bc","enabled":true,"type":"default"},{"key":"rural_address","value":"{\n    \"first_name\" : \"John\",\n    \"last_name\" : \"Doe\",\n    \"street1\" : \"2708 4th St\",\n    \"city_locality\" : \"Bay City\",\n    \"state_province\" : \"TX\",\n    \"postal_code\" : \"77414\",\n    \"country_code\" : \"US\"\n}","enabled":true,"type":"default"},{"key":"rateSetIdTicon2025","value":"b9099ca4-e05e-4110-96e8-783b60502d37","enabled":true,"type":"default"},{"key":"maerskUserId","value":"","enabled":true,"type":"default"},{"key":"access_token","value":"","enabled":true,"type":"any"},{"key":"pb_access_token","value":"","enabled":true,"type":"any"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/23f2ec4092409e063015c97e685e063146fb2f5a1f5baac5089eedf7aea3aa24","favicon":"https://commerceship.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"production","value":"24641535-a3a4ea4f-a652-4560-ac15-e3ff30e07be7"}],"canonicalUrl":"https://docs.commerceship.com/view/metadata/2s9YkgE5eg"}