{ "openapi": "3.1.0", "info": { "title": "ShippyPro API v1", "version": "1.0.0", "description": "Welcome to ShippyPro Developer Portal โ€” a comprehensive reference guide to\n**the most complete Shipping and Logistic API suite**.\nHere you can access to **40+ API methods** to cover all your business cases\nimproving efficiency, reducing operations time/costs and delighting your\ncustomer with a **next level shipping service**.\n\nYou can find other information in the API section\n[ShippyPro Help Center](https://help.shippypro.com/en/knowledge/api).\n\n## Overview\n\nShippyPro API is the easiest way to integrate your system with **hundreds of\ncarriers worldwide** to ship your packages. Check our complete **integration\nlibrary** [here](https://www.shippypro.com/en/integrations/).\n\nWe study the e-commerce and the logistics industry every day with the goal of\nfurther optimizing the shipping process and making this activity easier for any\nvendor.\n[Here](https://help.shippypro.com/en/knowledge/articles/3306113-how-shippypro-api-works)\nis a simple guide to help you with the integration of ShippyPro APIs.\n\n**The ShippyPro multi-carrier APIs allows developers to build applications that\ninterface with the ShippyPro platform. The APIs can be used to automate many\ntasks including:**\n- Managing Shipments\n- Creating Shipping Labels\n- Get Shipping Rates\n- Get Tracking\n- Schedule Pickup\n- Download orders etc.\n\n## Base endpoint\n\nAll API requests must be made over HTTPS to the following base endpoint:\n\nhttps://api.shippypro.com/`version`\n\n๐Ÿ“Œ You can find the current version in the section below!\n\n## Versioning\n\nThe current version of ShippyPro API is `v1`. This is the endpoint to reach:\n\nhttps://api.shippypro.com/v1\n\n## API specification\n\nShippyPro exposes a **REST API**, you need to send a well-formed JSON POST\nrequest containing Method and Params parameters.\n\n## SOAP version\n\nWe also offer a SOAP API version. At this\n[link](https://www.shippypro.com/wsdl/shippypro.wsdl) you can find the WSDL.\n\n## Webhook\n\nShippyPro webhooks are used to send real-time events to external listeners to\nprovide the ability to receive orders, shipments, and tracking updates in\nreal-time.\nWhen a webhook is triggered, ShippyPro sends a POST request to the webhook's\ncallback URL.\n\nSee\n[how to connect webhooks](https://help.shippypro.com/en/knowledge/articles/4134207-how-do-i-connect-webhooks)\nin the Help Center for the setup steps.\n\n## APIs and features\n\nEach endpoint and feature is identified with the module associated with.\n\n| API Method | Description |\n|---|---|\n| `ArchiveOrders` | Archives shipments or orders |\n| `BookPickup` | Books a Pick-Up for all supported carriers |\n| `CancelPickup` | Cancels a scheduled pickup for all supported carriers |\n| `CheckAddress` | Checks if an address is valid |\n| `CloseMasterShipment` | Closes a Bulk Shipping flow |\n| `CloseShipments` | Confirms shipments to carriers |\n| `CreateInvoice` | Generates and get order summary or invoices |\n| `CreateManifest` | Creates Manifest documents |\n| `CreateMasterShipment` | Returns a new Master Shipment ID for carriers featuring Bulk Shipping |\n| `DeleteManifest` | Deletes Manifest documents |\n| `DeletePaperlessDocumentation` | Deletes unused uploaded ETD/paperless documents by TransactionID or recipient Name |\n| `DeletePendingOrder` | Deletes an order yet to be shipped |\n| `EditPendingOrders` | Edit the orders yet to be shipped |\n| `GetCarrierOptions` | Gets the available Carrier options for a specific Carrier |\n| `GetCarrierPackagesTypes` | Gets the available carrier packages types |\n| `GetCarriers` | Gets the list of connected carriers and their details in your ShippyPro profile |\n| `GetDetailedPricing` | Returns the detailed estimated pricing calculated for one order |\n| `GetDropOffPoints` | Retrieves nearest Pick Up DropOff points (PUDO) |\n| `GetDropOffInfo` | Retrieves a single Pick Up DropOff point given an ID |\n| `GetLabelUrl` | Retrieves order labels and tracking info |\n| `GetManifest` | Retrieve Manifest documents |\n| `GetMarketplaces` | Returns all the Marketplaces IDs already connected to your ShippyPro account |\n| `GetOrder` | Retrieves order or shipment details |\n| `GetPendingOrders` | Returns the orders list yet to be shipped |\n| `GetPickupAvailability` | Retrieves Pick Up availability for all supported carriers |\n| `GetPickups` | Returns the list of scheduled pickups for all supported carriers |\n| `GetPOD` | Returns the Proof of Delivery of a shipment once delivered |\n| `GetPODDocument` | Returns a PDF document including the Proof of Delivery and shipment details |\n| `GetPrinters` | Retrieves connected ShippyPro printers |\n| `GetReturnsReport` | Returns the list of returns in the specified timeframe |\n| `GetShipmentsReport` | Returns the list of shipments in the specified timeframe |\n| `IsPendingOrder` | Returns true if an order is being shipped |\n| `IsResidentialAddress` | Checks if an address is residential |\n| `MarkOrdersAsPrinted` | Marks orders as printed |\n| `PutShippedOrder` | Imports external orders already shipped inside your ShippyPro profile |\n| `UpdateOrders` | Send shipments information to marketplaces |\n| `UploadPaperlessDocumentation` | Submits custom documents to carriers |\n| `UploadPaperlessPostShip` | Submits custom documents to carriers after the shipment |\n| `CreateCrossBorderInvoice` | Generates a Cross Border Invoice |\n\n| Feature | Description |\n|---|---|\n| `Return Label Combination` | Used in the Ship API method allows you to specify a different carrier for a return |\n| `Return Address Override` | Used with Return Label Combination in the Ship API method, allows you to specify a different return address |\n\nFor a custom quotation to access these features please\n[contact us](https://www.shippypro.com/contact-us.html).\n\n# Getting started\n\nHow to get your credentials and make the first API call.\n\n## Get your credentials\n\nYou can create a free ShippyPro account\n[here](https://www.shippypro.com/register.html).\n\n## Authentication\n\nEvery API request must be authenticated with a **Bearer token** โ€” your\n**API Key**, sent in the `Authorization` header.\n\nYou can find or generate your **API Key** under the API section\n[Here](https://www.shippypro.com/panel/apikeys.html) in ShippyPro (e.g.\n`your-API-Key`).\n\nSend it with every request as follows:\n\n`Authorization: Bearer your-API-Key`\n\n## Partner identification\n\nIf you are integrating ShippyPro into your platform on behalf of your users,\ninclude the `Referer` HTTP header with your partner name in all API requests.\nThis allows ShippyPro to identify and support your integration.\n\nFor example:\n\n`Referer: your-partner-name`\n\n๐Ÿ“Œ **Note!** Use a consistent, lowercase identifier (e.g. `my-platform`,\n`acme-wms`). Contact your ShippyPro account manager for your assigned partner\nname.\n\n## Get Carrier ID\n\nAfter you have generated the API KEY you would need to add at least one carrier\nfrom [Carrier page](https://www.shippypro.com/panel/my-couriers.html).\nYou can find a detailed guide on how to connect your carriers in **ShippyPro\nHelp Center**\n[here](https://help.shippypro.com/en/knowledge/articles/3340008-how-to-connect-your-carriers).\n\nAfter you have connected at least one Carrier, you will be able to get\n`CarrierID`, `CarrierName`, and `CarrierService` at the bottom of the\n[API Keys page](https://www.shippypro.com/panel/apikeys.html).\n\n## Order ID\n\nThe `OrderID` number is the unique ID given to the order at the time it was\nprocessed. It's a **ShippyPro generated number** and no edits are possible.\n\nSave this number once you generate a new shipment in order to do further API\ncalls related to that order.\n\nIf you need to reference **your internal order ID number** you can use the\n`TransactionID` field.\n\n## Server responses\n\n| Status code | Description |\n|---|---|\n| `200` | OK - The request was successful (some API calls may return 201 instead). |\n| `400` | Bad Request - The request could not be understood or was missing the required parameters. |\n| `401` | Unauthorized - Authentication failed or the user does not have permissions for the requested operation. |\n| `403` | Forbidden - Access denied. |\n| `404` | Not Found - Resource was not found. |\n| `429` | Too many requests. See [here](#v1/description/api-rate-limit) for specification. |\n| `500` | Internal Server Error - ShippyPro has encountered an error. |\n\n## DateTime format\n\nShippyPro uses the **Unix Time for Date and Time** fields.\n\nPlease refer to https://en.wikipedia.org/wiki/Unix_time for more information\nabout Unix time.\n\n**Timezone**\n\nShippyPro use CET as timezone, this means that if you use a unix time stamp\ndate, CET timezone will be considered.\nPlease note that some Carriers could have specific time zone value for date time\nparameters, please check with carrier which one should be used.\n\n## List of currencies\n\nHere's the list of the accepted currencies (use the 3-length ISO code).\n\n| Currency | ISO-4217 |\n|---|---|\n| United States Dollar | `USD` |\n| European Euro | `EUR` |\n| British Pound Sterling | `GBP` |\n| Japanese Yen | `JPY` |\n| Canadian Dollar | `CAD` |\n| Australian Dollar | `AUD` |\n| Swiss Franc | `CHF` |\n| Chinese Yuan Renminbi | `CNY` |\n| Indian Rupee | `INR` |\n| Russian Ruble | `RUB` |\n| Singapore Dollar | `SGD` |\n| Swedish Krona | `SEK` |\n| South Korean Won | `KRW` |\n| Mexican Peso | `MXN` |\n| New Zealand Dollar | `NZD` |\n| Danish Krone | `DKK` |\n| Norwegian Krone | `NOK` |\n| Polish Zloty | `PLN` |\n| Malaysian Ringgit | `MYR` |\n| Saudi Arabian Riyal | `SAR` |\n| Qatari Riyal | `QAR` |\n| Turkish Lira | `TRY` |\n| Indonesian Rupiah | `IDR` |\n| UAE Dirham | `AED` |\n| Philippine Peso | `PHP` |\n| Romanian Leu | `RON` |\n| Bulgarian Lev | `BGN` |\n| Czech Koruna | `CZK` |\n| Hungarian Forint | `HUF` |\n| South African Rand | `ZAR` |\n| Thai Baht | `THB` |\n| Kuwaiti Dinar | `KWD` |\n| Egyptian Pound | `EGP` |\n| Israeli New Shekel | `ILS` |\n| Lebanese Pound | `LBP` |\n| Macanese Pataca | `MOP` |\n| Ukrainian Hryvnia | `UAH` |\n| Moroccan Dirham | `MAD` |\n| New Taiwan Dollar | `TWD` |\n| Peruvian Sol | `PEN` |\n| Vietnamese Dong | `VND` |\n| Albanian Lek | `ALL` |\n| Azerbaijani Manat | `AZN` |\n| Moldovan Leu | `MDL` |\n| Kazakhstani Tenge | `KZT` |\n| Serbian Dinar | `RSD` |\n\n## API rate limit\n\nThere is a Rate-Limiting of 20 API requests every 10 seconds.\n\nThis means that you can do 10 API calls in one second but then you will only\nhave 10 remaining API calls for the next nine seconds.\n\nWhen request submissions exceed this limit, the API will return the error:\n429 Too Many Requests.\n\n๐Ÿ“Œ The default rate limit can be increased for a premium fee for further\ninformation please [contact sales](https://www.shippypro.com/en/contact-us/).\n\n## Use cases\n\nHere you can find the most common ShippyPro API integration scenarios.\n\n- **Checkout** โ€” how to use the ShippyPro API in your ecommerce store checkout.\n ![checkout](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-01-Checkout-Flow.jpg)\n- **Shipments** โ€” how to use the ShippyPro API to handle a shipment.\n ![shipments](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-02-Ship-Flow.jpg)\n- **Tracking** โ€” how to use the ShippyPro API to get shipments tracking.\n ![tracking](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-03-Tracking-Flow.jpg)\n- **Webhook** โ€” how to use the ShippyPro API to get real time shipments update.\n ![webhook](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-03-Webhook-Flow.jpg)\n- **Orders** โ€” how to use the ShippyPro API to handle orders.\n ![orders](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-04-Manage-Orders-Flow.jpg)\n- **Print** โ€” how to use the ShippyPro API to print labels.\n ![print](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-05-Print-Flow.jpg)\n- **Returns** โ€” how to use the ShippyPro API to get shipments tracking.\n ![returns](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-06-Returns-Flow.jpg)\n- **Proof of Delivery** โ€” how to use the ShippyPro API to get proof of delivery.\n ![pod](https://cdn.shippypro.com/assets/images/api-use-cases/ShippyPro-API-Use-Cases-07-POD-Flow.jpg)\n\n### Other tips\n\n- If you want to **import your orders** from your System (ERP, WMS, OMS) to ShippyPro: use **[PutOrder](#v1/tag/orders/POST/v1/PutOrder)** API.\n- To upload the **ETD documents**, call the **[UploadPaperlessDocumentation](#v1/tag/paperless/POST/v1/UploadPaperlessDocumentation)** API before the **[Ship](#v1/tag/shipments/POST/v1/Ship)** API. The TransactionID, Name, and Country fields must match the one of the order (case sensitive).\n- To get the **carriers prices** for the shipment and create the shipping label: use **[GetRates](#v1/tag/shipments/POST/v1/GetRates)** and then **[Ship](#v1/tag/shipments/POST/v1/Ship)** APIs.\n- To **book the carrier pickup** use the **[BookPickup](#v1/tag/pickup/POST/v1/BookPickup)** always after the **[Ship](#v1/tag/shipments/POST/v1/Ship)** API.\n- To create the **end of day manifest** with the summary of all the shipments to be given to the carrier by using the **[CreateManifest](#v1/tag/manifest/POST/v1/CreateManifest)** API call.\n- To confirm all the shipments that will depart by using **[CloseShipments](#v1/tag/manifest/POST/v1/CloseShipments)**, **only** for carriers that request it.\n- To **ship an order whose parcel count is not known in advance** (progressive multiparcel), send one **[Ship](#v1/tag/shipments/POST/v1/Ship)** call per parcel with `IsDynamicMultiparcel: true` and then close it with **[CloseShipments](#v1/tag/manifest/POST/v1/CloseShipments)**. See the Progressive Multiparcel section of the Ship method.\n- To **track orders use webhooks** by configuring them from the API page inside the ShippyPro platform. Otherwise use the **[GetTracking](#v1/tag/shipments/POST/v1/GetTracking)** call but is not our recommended option.\n- To **cancel a pickup** use the **[CancelPickup](#v1/tag/pickup/POST/v1/CancelPickup)** call (valid only for some carriers please check if the selected carrier supports this call [here](https://www.shippypro.com/en/carriers-comparison-map/)).\n- To **add some options to the shipment** it is necessary to get their definitions first with the **[GetCarrierOptions](#v1/tag/carriers/POST/v1/GetCarrierOptions)** API call and then add them to the Ship call by using the CarrierOptions tag\n- To **make changes to an order** created using the Ship API:\n - Change the method inside the โ€œShipโ€ API with โ€œEditโ€.\n - Change the desired fields.\n - Insert in the โ€œOrderIDโ€ field the order number received in the response to the Ship API.\n- To **cancel a shipment** (valid only for some carriers please check if selected one support this option [here](https://www.shippypro.com/en/carriers-comparison-map/)) use **[VoidShipments](#v1/tag/orders/POST/v1/VoidShipments)**.\n- To add **customs declaration for international shipment**, please go to the International Shipments section inside the **[Ship](#v1/tag/shipments/POST/v1/Ship)** and follow the instructions.\n\n## Status page\n\nWe provide transparency around service availability and performance for\nShippyPro products.\nHere you can find our\n[ShippyPro Status Page](https://status.shippypro.com) where you can check\nstatus for\n\n- ShippyPro Systems Stack\n- Carriers\n- Marketplaces\n- Other Services\n\nYou can also subscribe to get informed whenever an incident is triggered.\n\n![statuspage](https://cdn.shippypro.com/assets/images/ShippyPro-StatusPage.png)\n", "x-logo": { "url": "https://public-website-hb.shippypro.com/hubfs/ShippyProLogo%20-%20AppIcon.png", "altText": "ShippyPro" }, "contact": { "name": "ShippyPro Engineering" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.shippypro.com", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Shipments" }, { "name": "Addresses" }, { "name": "Pickup" }, { "name": "Marketplaces" }, { "name": "Carriers" }, { "name": "Manifest" }, { "name": "Paperless" }, { "name": "Orders" }, { "name": "Printing" }, { "name": "Dropoff Points" }, { "name": "Whitelabels" }, { "name": "Webhooks", "description": "ShippyPro uses webhooks to notify your application when an event happens\nin your account. Webhooks are particularly useful for asynchronous events\nlike when a carrier confirms a label creation, a shipment tracking or an\nerror.\n\n**How ShippyPro uses webhooks**\n\nA webhook enables ShippyPro to push real-time notifications to your app.\nShippyPro uses HTTPS to send these notifications to your app as a JSON\npayload. You can then use these notifications to execute actions in your\ne-commerce store, applications or backend systems.\n\n**How to connect webhooks**\n\nFor more informations on how to connect ShippyPro webhooks please check\nour help article\n[here](https://help.shippypro.com/en/knowledge/articles/3306113-how-shippypro-api-works-and-how-to-integrate-them).\n" }, { "name": "Monitoring" } ], "paths": { "/v1/Ship": { "post": { "operationId": "Ship", "summary": "Ship", "description": "``Shipping Platform``\n\nThis method gives the possibility to generate a shipment or a return and get shipping labels with the same API call.\n\n๐Ÿ’กThis Method gives you the ability to:\n\n- Generate a standard shipment and get its label.\n\n- Generate a shipment with its return label to put in the box.\n\n- Generate a standard return.\n\n- Generate a return and override its return to address.\n\n- Generate a shipment with a carrier and generate return label with a different carrier.\n\n**How to test**\n\nFor testing purposes, you can use the ShippyPro Generic carrier for generating test labels. [See here](https://help.shippypro.com/en/knowledge/new-experience-how-to-use-a-generic-carrier) if you need help configuring ShippyPro Generic Carrier.\n\nโš ๏ธ Note! The data type of the response attribute LabelURL could be both an array or a string.\n- it's an empty array if the order is in error,[].\n- it's a string if the order has one label, \"label-url\".\n- it's an array of strings if the order has more than one label, [\"label-url-1\", \"label-url-2\", ...].\n\n๐Ÿ“Œ If you used PutOrder API to create an order to ship, you need to make the Ship API call with the same TransactionID used with the PutOrder API call, then the system will link the right order as well as the items.\n\n**Choosing a Carrier**\n\nPlease note that you must have at least a working carrier connection to make any shipment. For help or any information on how to connect a carrier, please check our help article [here](https://help.shippypro.com/en/knowledge/articles/3340008-how-to-connect-your-carriers). After you have connected at least one Carrier, you will be able to get CarrierID, CarrierName, and CarrierService at the bottom of the API Keys ShippyPro page.\n\n**Getting Carrier Rates**\n\nYou can use our GetRates API before of Ship call in order to choose the best carrier's rate option for your shipment and specify the RateID parameter in the Ship call.\n\n**Custom Attributes**\n\nShip API allows you to specify Order and Parcel custom attributes with a key value array in the request, which can be useful for marking or retrieving your shipments based on these values.\nThese values can also be printed on the shipment labels using our [Label Design](https://www.shippypro.com/en/label-design/) product, which allows you to customize labels.\n\n***Managed Attributes***\n\nSome of the attributes that can be added to a Ship request are recognized by the platform and they can be exploited to better manage the orders and their\ncustomizations.\n\n****sp_ioss****\n\nThe `sp_ioss` attribute makes it possible to bind an IOSS number. This data is used instead of the default one, specified in the Profile section, and eventually transmitted\nto the carriers.\n\n**Choosing Packages**\n\nYou can specify your own package dimensions or retrieve Carrier supported packages with the GetCarrierPackagesTypes method, see [here](#v1/tag/carriers/POST/v1/GetCarrierPackagesTypes) for method reference.\n\nExample of package specification in the Ship and Get Rates (Only FEDEX) methods call, where package attribute value corresponds to the \"value\" attribute obtained through the GetCarrierPackagesType method call.\n\n```js\n\"parcels\":[\n {\n \"package\":1,\n \"length\":5,\n \"width\":5,\n \"height\":5,\n \"weight\":10\n }\n]\n```\n\nIf you do not know how many parcels the shipment will have when you create the first label, see the **Progressive Multiparcel** section below.\n\n**Get the Labels (sync or async)**\n\nThe method works in async and sync way, giving you the ability to get return label in the response call or retrieve it later. Please refer to the Async parameter below , if false the label will be returned in call response, if true you should retrieve the label with the GetLabelURL or via Webhook - Order Shipped Events.\n\n**Paperless**\n\nIf you want to upload paperless documentation to you shipment, please check the [UploadPaperlessDocumentations](#v1/tag/paperless/POST/v1/UploadPaperlessDocumentation) API method.\n\n**Returns handling**\n\nIn ShippyPro a return is treated as a shipment, and you can decide how to fill the from and to address with your own logic.\nAnyway the easier way to create a return is setting `IsReturn: true` and reversing the sender and the recipient addresses.\n\n**Return Label in The Box**\n\nShippyPro support Return Label in The Box that gives you the ability to create Shipment and return label with one ship call. You should specify this setting in carrier connection form, the ship call will work accordingly with the carrier connection setting. If need help in setting the feature please read our help article [here](https://help.shippypro.com/en/knowledge/articles/6364864-how-to-offer-a-return-label-in-the-box).\n\nโš ๏ธ Warning: the ``ContentDescription`` field does not accept the backslash character as a valid character. Please do not enter a backslash in this field, as it may cause errors or data processing problems.\n\n### International Shipments\n\nIf you need to ship outside the EU you should provide the CN22 customs declaration module โ€” see the ``CN22Info`` parameter in the reference below. Including these parameters automatically generates the customs documents together with the label. The ``BillAccountNumber`` field should only be filled in when the Incoterm employed is EXW.\n\n+ To add customs declaration for international shipment. Add the following tag inside the Params field in the Ship request (one row for every item in the order):\n```js\n\"CustomInfoContentsType\" : \"merchandise\",\n\"CN22Info\": [\n {\n \"Description\": \"test\",\n \"Weight\": 2,\n \"Quantity\": 5,\n \"UnitValue\": 10,\n \"OriginCountry\": \"IT\",\n \"Currency\": \"USD\",\n \"HSCode\": \"123456\",\n \"EAN\": \"123456\",\n \"VOC\": \"12\"\n }\n]\n```\nThese fields are required for international shipments. Alternatively, the [UploadPaperless](#v1/tag/paperless/POST/v1/UploadPaperlessDocumentation) method is available (find out [here](https://help.shippypro.com/en/knowledge/articles/8880574-new-experience-how-to-manage-your-etd-documents) which carriers support this method).\n\n### Carrier Options\n+ To add some options to the shipment it is necessary to get their definitions first with the [GetCarrierOptions](#v1/tag/carriers/POST/v1/GetCarrierOptions) API call and then add them to the Ship call by using the CarrierOptions tag\n```js\n\"CarrierOptions\": [{\n \"name\": \"upsdangerousgoods\",\n \"value\": 1\n}]\n```\n\n### Return Label Combination & Return Address Override\nThe Ship method supports shipping with one carrier and returning the order with another. To specify a different carrier for return shipments please add this parameters to ship call.\nThe return_to array is optional and is needed only if you want to specify a different return address (e.g. a warehouse dedicated to returns). By default the tracking runs for 30 days after label creation; an extension to 120 days is possible.\n\n```js\n\"ReturnCarrierName\": \"Generic\",\n\"ReturnCarrierService\": \"Standard\",\n\"ReturnCarrierID\": 6,\n\"ReturnInsurance\": 10, // Optional - Default 0\n\"ReturnInsuranceCurrency\": \"EUR\", // Required if ReturnInsurance is set\n\"ReturnCarrierOptions\": [{ //optional\n \"name\": \"upsdangerousgoods\",\n \"value\": 1\n}],\n\"return_to\": {\n \"name\": \"John Doe\",\n \"company\": \"Shippypro\",\n \"street1\": \"Via Napoli 1\",\n \"street2\": \"\",\n \"city\": \"Roma\",\n \"state\": \"RM\",\n \"zip\": \"12345\",\n \"country\": \"IT\",\n \"phone\": \"+39123124567\",\n \"email\": \"sales@shippypro.com\"\n},\n```\n\n### Progressive Multiparcel\n\nProgressive (or *dynamic*) multiparcel covers shipments whose parcel count is **not known when the first parcel ships** โ€” typically B2B orders that the warehouse packs over the course of a day. It is also called *multi-collo progressivo*, or the add-parcel flow.\n\nWith ordinary (*static*) multiparcel you declare every parcel in the ``parcels`` array of a single Ship call. With progressive multiparcel you send **one Ship call per parcel**, each flagged with ``IsDynamicMultiparcel: true``, as the parcels are packed. Every call returns that parcel's label straight away, so the box can be labelled and closed without waiting for the rest of the order.\n\n**How parcels are grouped**\n\nShippyPro groups the flagged shipments for you. All four parts of the group key must match:\n\n- the **receiver**, taken from ``to_address``: ``name``, ``company``, ``street1``, ``street2``, ``city``, ``state``, ``zip`` and ``country``, compared case-insensitively with surrounding and repeated whitespace ignored,\n- the **sender address**, taken from ``from_address``: ``street1``, ``street2``, ``city``, ``state``, ``zip`` and ``country``, compared the same way,\n- the **carrier connection**,\n- the **ShippyPro account**.\n\nThe first flagged shipment opens the group; every later one joins it and takes the next parcel number. The group accepts new parcels for **5 days (120 hours)** from its first parcel. After that, the next parcel opens a new group. Reaching 5 days does not close the group: the earlier group still has to be closed with [CloseShipments](#v1/tag/manifest/POST/v1/CloseShipments). The day is not part of the key, so a group does not split at midnight.\n\nโš ๏ธ ``phone`` and ``email`` are **not** part of the receiver key, and neither are the sender's ``name`` and ``company`` โ€” only the sender's address counts. Every field that is part of the key must match across the parcels of one shipment. Send the receiver ``name`` and ``company`` identically on every call: a difference in any key field, down to a typo in the street, starts a second group and splits the shipment in two.\n\n๐Ÿ“ฆ Parcels that leave **different warehouses** never group, even for one receiver in one window. Ship each origin with its own ``from_address``: each becomes its own shipment, with its own origin.\n\n๐Ÿ“Œ The 5 days are counted from the first parcel of the group, not from a calendar day, so your local time and the UTC boundary do not matter.\n\n``TransactionID`` is not part of the key and does not have to be unique per call, so you can carry your own order reference on every parcel of the shipment.\n\n**Closing the shipment**\n\nThe Ship calls only produce labels. The carrier is told about the complete shipment at **closeout**, and until then the shipment is not confirmed.\n\nClose it with [CloseShipments](#v1/tag/manifest/POST/v1/CloseShipments), or via *Close Work Day* in the ShippyPro application where that is available for your carrier.\n\nโš ๏ธ **A group closes whole.** Naming one parcel of a progressive shipment in ``OrderIDS`` closes every parcel of its group, not just the one you named, and the carrier then expects all of them. There is no way to close a single parcel on its own.\n\n``OrderIDS`` still narrows *which* groups a call touches: pass it and the call acts on the orders you list, each expanded to its group. Omit it and the call takes every order for that carrier that has not been closed yet, going back one month โ€” across every receiver and every connection to that carrier.\n\nSo the only way to keep an already-shipped parcel out of its group is [VoidShipments](#v1/tag/orders/POST/v1/VoidShipments), called **before** the closeout. A parcel that is neither voided nor wanted still goes to the carrier.\n\nRe-closing is safe: a parcel already transmitted in an earlier closeout is skipped rather than sent twice.\n\n**A closeout seals the group.** Parcels shipped afterwards do not join the shipment you have just closed, even to the same receiver: they open a new group, which the next closeout confirms as a second shipment to the carrier. Closing part-way through the day is therefore a real choice, not a mistake โ€” it simply means the order reaches the carrier as more than one shipment.\n\n**Close before 5 days pass.** A group does not split at midnight: parcels shipped on different days join the same group, and a closeout started from any one of them closes all of them. A group accepts new parcels for 5 days (120 hours) from its first parcel. Parcels shipped after that go to a new group, which needs its own closeout, and reaching 5 days does not close the earlier group: close it with CloseShipments. Closing at the end of each working day keeps what the carrier expects aligned with what you packed. Running the closeout more than once is fine.\n\nA **scheduled closeout** is available for a subset of carriers. Where your carrier supports it, it runs at a fixed time each day, is configured per carrier connection under *Utilities โ†’ Task scheduler* in the ShippyPro application, and any parcel added after that time stays open and rolls into the next closeout. Ask your ShippyPro account manager whether it is an option on your connection.\n\n**Availability**\n\nProgressive multiparcel is driven entirely from the Ship API โ€” there is no switch in the web application, and ``IsDynamicMultiparcel`` is the only thing that selects it. The same carrier connection serves both static and progressive shipments.\n\nSupport depends on the carrier and on the terms of your contract, and the list keeps growing. To find out whether it is available on yours, please [contact us](https://www.shippypro.com/en/contact-us/) or ask your ShippyPro account manager before integrating.\n\n**Example**\n\n```js\n// 09:00 โ€” the first box is packed. Repeat this call for every parcel, keeping the\n// same sender address, receiver address, day and carrier connection. Each call\n// returns its label.\n{\n \"Method\": \"Ship\",\n \"Params\": {\n \"IsDynamicMultiparcel\": true,\n \"TransactionID\": \"ORDER-4711\",\n \"CarrierName\": \"YourCarrier\",\n \"CarrierService\": \"Standard\",\n \"CarrierID\": 12,\n \"parcels\": [ { \"length\": 40, \"width\": 30, \"height\": 20, \"weight\": 12.5 } ]\n // ...to_address, from_address, ContentDescription as usual\n }\n}\n\n// End of the working day โ€” the closeout confirms the group to the carrier.\n// Naming any one parcel closes every parcel of its group. Omit OrderIDS to close\n// every un-closed order for this carrier from the last month instead.\n{\n \"Method\": \"CloseShipments\",\n \"Params\": {\n \"CarrierName\": \"YourCarrier\",\n \"OrderIDS\": [1234]\n }\n}\n```\n\n### Per-Parcel Data\nThe Ship response includes a per-parcel breakdown of the trackings and labels emitted by the carrier through the ``Parcels`` and ``ReturnParcels`` arrays. The same data is also returned by [GetLabelUrl](#v1/tag/orders/POST/v1/GetLabelUrl).\n\n**Outbound parcels โ€” ``Parcels``**\n\nOne entry per physical outbound parcel. ``null`` when no parcel has both a tracking number and a label (e.g. the carrier returned only customs forms). For shipments where the carrier returns a *Return Label In The Box* (RLITB) alongside the outbound label, the return label is also emitted as an item in this same array โ€” see \"Identifying return parcels\" below.\n\nField |Data Type |Description\n------------------|-----------------|------------------------------------------------------------------------------------\n``TrackingNumber``|string |Per-parcel tracking code.\n``PDF`` |string \\| null |Base64-encoded PDF of this parcel's label (one page per parcel). ``null`` if the carrier did not return a PDF.\n``ZPL`` |string \\| null |Raw ZPL label string for this parcel. ``null`` if the carrier did not return a ZPL.\n``Attributes`` |object |Per-parcel attributes (free-form name โ†’ value, e.g. UDC). Empty object if no attributes are stored.\n\n**Return parcels โ€” ``ReturnParcels``**\n\nOne entry per physical return parcel. Only present when the Ship request used a **Return Label Combination** (i.e. specified ``ReturnCarrierName`` / ``ReturnCarrierID`` / ``ReturnCarrierService``). Absent for outbound-only shipments and for RLITB.\n\nField |Data Type |Description\n------------------|-----------------|------------------------------------------------------------------------------------\n``TrackingNumber``|string |Per-parcel return tracking code.\n``PDF`` |string \\| null |Base64-encoded PDF of the return label for this parcel.\n``ZPL`` |string \\| null |Raw ZPL of the return label for this parcel.\n``Attributes`` |object |Mirrored positionally from ``Parcels[i].Attributes``. Return parcel attributes are not stored independently โ€” they are copied positionally from the outbound parcel at the same index. If there is no corresponding outbound parcel at that index, ``Attributes`` is an empty object.\n\n**Identifying return parcels**\n\n- **Return Label Combination (RLC)** โ€” outbound parcels are in ``Parcels``, return parcels are in ``ReturnParcels``. Clearly separated.\n- **Return Label In The Box (RLITB)** โ€” outbound and return labels are both emitted inside ``Parcels`` with no marker indicating which is which. This is a current limitation of the data model: RLITB labels are stored against the same order with no per-row \"outbound vs return\" flag. Clients that need to distinguish them must rely on out-of-band knowledge (e.g. the order configuration) or carrier-specific conventions.\n\n**Worked examples**\n\nOutbound 2-parcel + RLC return:\n```js\n{\n \"Parcels\": [ { \"TrackingNumber\": \"OUT-1\", \"...\": \"...\" }, { \"TrackingNumber\": \"OUT-2\", \"...\": \"...\" } ],\n \"ReturnParcels\": [ { \"TrackingNumber\": \"RET-1\", \"...\": \"...\" }, { \"TrackingNumber\": \"RET-2\", \"...\": \"...\" } ]\n}\n```\n\nOutbound 2-parcel + RLITB (the two return entries are not distinguishable from the outbound ones):\n```js\n{\n \"Parcels\": [\n { \"TrackingNumber\": \"OUT-1\", \"...\": \"...\" },\n { \"TrackingNumber\": \"OUT-2\", \"...\": \"...\" },\n { \"TrackingNumber\": \"RET-1\", \"...\": \"...\" },\n { \"TrackingNumber\": \"RET-2\", \"...\": \"...\" }\n ]\n}\n```\n\nOutbound-only:\n```js\n{\n \"Parcels\": [ { \"TrackingNumber\": \"OUT-1\", \"...\": \"...\" } ]\n}\n```\n", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "Ship" }, "Params": { "$ref": "#/components/schemas/ShipParams" } } }, "examples": { "singleParcel": { "summary": "One parcel, one label", "description": "The common case: the whole shipment is one parcel, sent in one call.\n", "value": { "Method": "Ship", "Params": { "to_address": { "name": "John Doe", "company": "", "street1": "123 Main St", "street2": "", "city": "Park City", "state": "UT", "zip": "84060", "country": "US", "phone": "5551231234", "email": "johndoe@gmail.com" }, "from_address": { "name": "ShippyPro", "company": "ShippyPro", "street1": "Via Napoli 1", "street2": "", "city": "Roma", "state": "RM", "zip": "00184", "country": "IT", "phone": "+39123124567", "email": "sales@shippypro.com" }, "parcels": [ { "length": 5, "width": 5, "height": 5, "weight": 10 } ], "TransactionID": "ORDER-4711", "ContentDescription": "Cotton t-shirts", "CarrierName": "Generic", "CarrierService": "Standard", "CarrierID": 6, "Async": false } } }, "multiparcel": { "summary": "Several parcels in one call (parcel count known up front)", "description": "One Ship call carrying every parcel of the shipment in the `parcels`\narray. Use this whenever you know the full parcel count at label\ncreation time. The response returns one label per parcel โ€” see\n*Per-Parcel Data*.\n", "value": { "Method": "Ship", "Params": { "to_address": { "name": "John Doe", "company": "", "street1": "123 Main St", "street2": "", "city": "Park City", "state": "UT", "zip": "84060", "country": "US", "phone": "5551231234", "email": "johndoe@gmail.com" }, "from_address": { "name": "ShippyPro", "company": "ShippyPro", "street1": "Via Napoli 1", "street2": "", "city": "Roma", "state": "RM", "zip": "00184", "country": "IT", "phone": "+39123124567", "email": "sales@shippypro.com" }, "parcels": [ { "length": 5, "width": 5, "height": 5, "weight": 10 }, { "length": 40, "width": 30, "height": 20, "weight": 12.5 }, { "length": 40, "width": 30, "height": 20, "weight": 8 } ], "TransactionID": "ORDER-4712", "ContentDescription": "Cotton t-shirts", "CarrierName": "Generic", "CarrierService": "Standard", "CarrierID": 6, "Async": false } } }, "dynamicMultiparcel": { "summary": "Progressive multiparcel โ€” one call per parcel, closed with CloseShipments", "description": "For shipments whose parcel count is not known when the first parcel\nships. Repeat this call once per parcel; ShippyPro groups the flagged\nshipments sharing sender address, receiver address,\ncarrier connection and account into one shipment, and each call returns\nthat parcel's label.\n`TransactionID` does not have to be unique per call, so every parcel can\ncarry your own order reference. Confirm the whole group to the carrier\nwith `CloseShipments` at the end of the working day. Availability depends\non the carrier and on your contract โ€” see *Progressive Multiparcel*.\n", "value": { "Method": "Ship", "Params": { "to_address": { "name": "John Doe", "company": "Acme Logistics", "street1": "123 Main St", "street2": "", "city": "Park City", "state": "UT", "zip": "84060", "country": "US", "phone": "5551231234", "email": "johndoe@gmail.com" }, "from_address": { "name": "ShippyPro", "company": "ShippyPro", "street1": "Via Napoli 1", "street2": "", "city": "Roma", "state": "RM", "zip": "00184", "country": "IT", "phone": "+39123124567", "email": "sales@shippypro.com" }, "parcels": [ { "length": 40, "width": 30, "height": 20, "weight": 12.5 } ], "TransactionID": "ORDER-4713", "ContentDescription": "Cotton t-shirts", "CarrierName": "YourCarrier", "CarrierService": "Standard", "CarrierID": 12, "IsDynamicMultiparcel": true, "Async": false } } } } } } }, "responses": { "200": { "description": "Shipment created (inspect `Status` / `ErrorMessage` for per-label outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/Edit": { "post": { "operationId": "Edit", "summary": "Edit", "description": "``Shipping Platform``\n\nThis method gives the possibility to modify a previously created shipment.\nThe method structure is the same of the **[Ship](#v1/tag/shipments/POST/v1/Ship)** API method, but the **OrderID** parameter must match with an existing ShippyPro order ID.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- modify or correct an error in any shipment.\n- get a new corrected shipment label.\n\n๐Ÿ“Œ Please note that every time you modify a shipment a **new label** will be generated.\n\n๐Ÿ“Œ This method works fine together with Order Error [Webhook](#v1/tag/webhooks/webhook/POST/ordererror), that enables to get each error shipments in realtime.\n", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "Edit" }, "Params": { "$ref": "#/components/schemas/EditParams" } } } } } }, "responses": { "200": { "description": "Shipment edited (inspect `Status` / `ErrorMessage` for outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/Edit-Partial": { "post": { "operationId": "EditPartial", "summary": "Edit - Partial", "description": "``Shipping Platform``\n\nThis method gives the possibility to modify a previously created shipment like the normal Edit call but only for specific fields. In this case a new label won't be generated\n", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "Edit" }, "Params": { "$ref": "#/components/schemas/EditPartialParams" } } } } } }, "responses": { "200": { "description": "Shipment fields updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditPartialResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetRates": { "post": { "operationId": "GetRates", "summary": "GetRates", "description": "``Shipping Platform``\n\nThis method retrieves the Carrier rates for a specific shipment with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieving all your Carriers' Rates in real time.\n- Compare your carrier rates to choose the best options during order fulfillment.\n- Improve conversion rate showing live rates at your checkout\n- Apply a markup on top of your shipment costs.\n\n\n**Applying Shipping Rules**\n\nIf you want to apply the Shipping rules in the GetRates you should:\n\n- Select the API folders as a specific source in the Shipping rule\n- Perform the PutOrder call adding the \"APIOrdersID\" that you can find in the Marketplace section\n- Perform the GetRates call entering the \"TransactionID\" obtained with the PutOrder\n\n**How to test**\nFor testing purposes, you can use the ShippyPro Generic carrier for generating test rates.\nSee [here](https://help.shippypro.com/en/knowledge/new-experience-how-to-use-a-generic-carrier) if you need help configuring ShippyPro Generic Carrier.\n\n๐Ÿ“Œ You can also add CarrierOptions attribute to get rates for specific carrier services.\n\n๐Ÿ“Œ GetRates API will work according to the Shipping Rules applied. If your GetRates call returns no Rates and no errors for a specific shipment, make sure your Shipping Rules are correctly set up and not blocking those SKUs.\n\n๐Ÿ“Œ Remember to value the TransactionID of the order in the API_GetRates in order to use the ShippingService rule, otherwise it will be skipped. If the field TransactionID is not populated, the filter for ShippingService can't be applied. Assigning a TransactionID value that does not match that of an order to ship will skip the application of the ShippingService filter.\n\n๐Ÿ“Œ If your GetRates rates donโ€™t match the rate shown in โ€œTo Shipโ€, make sure both GetRates and your My Profile > Preferences units of measure correspond!\n\n๐Ÿ“Œ By referring the RateID from Shipping API call response you'll also be able to use our Invoice Analysis feature.\n\n๐Ÿ“Œ You can filter this call for specific services by filling out the RateCarriers field with CarrierName and CarrierID, that you can retrieve from the APIKEYS ShippyPro page.\n\nE.G ``RateCarriers: [\"CarrierName|CarrierID\", \"CarrierName|CarrierID\"]``\n\n๐Ÿ“Œ You can also add ``CarrierOptions`` attribute (see Use Cases section).\n\nโš ๏ธ Note that the response attribute ``delivery_days`` could be both a number (e.g. 2) or a string (e.g. \"2-5\").\n\nโš ๏ธ In the GetRates response, you may find a section labeled ``RatesErrors`` that includes the field ``error_level``. The values that could be displayed are the following:\n- ``0``: Error (the rate could not be pulled for a Carrier Error);\n- ``1``: Warning (the rate pulling was stopped because of a fixable error coming from ShippyPro, like โ€œno zones matching shipment infoโ€ or โ€œcarrier/shipping rule excluded this rateโ€);\n", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetRates" }, "Params": { "$ref": "#/components/schemas/GetRatesParams" } } } } } }, "responses": { "200": { "description": "List of available carrier rates (and any per-carrier errors)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRatesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetTracking": { "post": { "operationId": "GetTracking", "summary": "GetTracking", "description": "``Tracking System``\n\nThis method retrieves the shipment tracking status with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieving shipment tracking status.\n- Show the shipment status in your website or OMS.\n- Get all the shipment status information as Estimated Delivery Date and the carrier logo.\n\nโš ๏ธ This method is not recommended for bulk usage. To receive all the trackings updates please setup a Webhook instead.\n\n**Order tracking statuses**\n\nTo simplify your work, we associated each carrier tracking statuses with this simple ShippyPro six statuses:\n\n### Order tracking statuses\nStatus Code | Description\n------------|-------------\n``1`` | Info Received\n``2`` | In Transit\n``3`` | Out for Delivery\n``4`` | Missed Delivery\n``5`` | Exception\n``6`` | Delivered\n\n**Extended Tracking Statuses**\n\nEvery tracking update is additionally mapped to an ExtendedStatusCode, representing a more granular status.\n\n### Extended Tracking Statuses\nExtended Status Code | Description\n------------|-------------\n``1000`` | Info Received\n``2000`` | In transit\n``2100`` | Dropped by customer\n``2200`` | Collected by carrier\n``2300`` | Carrier handling\n``2310`` | Arrived at terminal/hub\n``2320`` | Processing at terminal/hub\n``2330`` | Departed from terminal/hub\n``2400`` | Customs Clearance\n``2500`` | Delivery planned\n``3000`` | Out for Delivery\n``3100`` | Delivery in progress\n``3200`` | Available for pickup at PUDO/Facility\n``4000`` | Failed Attempt\n``5000`` | Generic Exception\n``5100`` | Transit Disruptions\n``5110`` | Delayed\n``5120`` | External causes\n``5200`` | Operational Issues\n``5210`` | Misrouted\n``5220`` | Pickup not possible\n``5230`` | On Hold\n``5300`` | Parcel Exception\n``5310`` | Exceeded dimensions or weight\n``5320`` | Damaged\n``5330`` | Lost\n``5340`` | Destroyed\n``5400`` | Address Discrepancies\n``5410`` | Insufficient address information\n``5420`` | Wrong address information\n``5500`` | Customs and Documentation\n``5510`` | Customs-related issues\n``5520`` | Missing documents\n``5600`` | Sender/Recipient-Related Events\n``5610`` | Recipient exception\n``5620`` | Sender exception\n``5630`` | Returning to sender\n``5640`` | Returned to sender\n``5700`` | Carrier Actions\n``5710`` | Carrier asks to be contacted\n``5720`` | Change to delivery\n``5730`` | Other Carrier Exception\n``6000`` | Delivered\n``6900`` | Manually Marked as Delivered\n``9999`` | Not mapped\n", "tags": [ "Shipments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetTracking" }, "Params": { "$ref": "#/components/schemas/GetTrackingParams" } } } } } }, "responses": { "200": { "description": "Tracking information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTrackingResponse" }, "example": { "Carrier": "UPS", "CarrierLogo": "https://www.shippypro.com/sites/all/themes/shippypro_theme/assets_pannello/images/corrieri/Logo_UPS.png", "Completed": true, "EstimatedDeliveryDate": "1489659960", "StatusCode": 6, "ExtendedStatusCode": 6000, "FirstStatusDate": "1489419660", "Late": false, "ExternalLink": "https://mailingtechnology.com/tracking/?tn=UD26123123456", "AdditionalTrackingNumbers": [], "Details": [ { "date": "1489659960", "message": "DELIVERED", "city": "MOTRIL", "StatusCode": 6 }, { "date": "1489625040", "message": "OUT FOR DELIVERY", "city": "GUARROMAN", "StatusCode": 3 }, { "date": "1489618800", "message": "ARRIVAL SCAN", "city": "GUARROMAN", "StatusCode": 2 }, { "date": "1489543200", "message": "DEPARTURE SCAN", "city": "ZARAGOZA", "StatusCode": 2 }, { "date": "1489443180", "message": "EXPORT SCAN", "city": "BOLOGNA", "StatusCode": 2 }, { "date": "1489429260", "message": "ORIGIN SCAN", "city": "PARMA", "StatusCode": 2 }, { "date": "1489419660", "message": "PICKUP SCAN", "city": "PARMA", "StatusCode": 2 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CheckAddress": { "post": { "operationId": "CheckAddress", "summary": "CheckAddress", "description": "``Address Validation``\n\nThis method allows you to check and validate shipping addresses for 240+ countries with just one call for all your Carriers.\nSince address structure varies from country to country in the response you'll find an accuracy indicator based on the level of accuracy of the result.\n\n๐Ÿ’ก Checking shipment addresses allows you to reduce:\n\n- errors during the shipment process and save operations time;\n\n- shipment exceptions and give your customers the best shipping experience;\n\n- Carrier shipment stock cost, in case of undeliverable addresses.\n\n**How the validation works**\n\nThe CheckAddress API takes the advantage to provide a **Carrier Side** and **GeoCoding** address validations.\n\nIf the carrier you are requesting to validate address supports address validation, the validation takes benefit of carrier validation, otherwise, a geocoding validation will take place. The carriers that support carrier side address validation are **GLS Italy** and **TNT Italy**. For every other carrier a GeoCoding validation takes place.\n\nIn both cases, the validation provides an accuracy score to let you understand how the address returned is accurate.\n\nYou can skip the carrier address validation setting **Generic** as carrier parameters.\n[See here](https://help.shippypro.com/en/knowledge/new-experience-how-to-use-a-generic-carrier) if you need help configuring ShippyPro Generic Carrier.\n\nFor each validated address you can get the following items in response:\n\n**Address Validation Messages**\n\nThey can be returned (if present) from the API carrier's response, and from GeoCoding.\n\n**Address Suggestions**\n\nThey can be returned (if present) only from the API carrier's response, not from GeoCoding.\n\n**New Address**\n\nIt is composed by replacing the fields reported as incorrect in the initial address, with the new values suggested.\n\n**Accuracy**\n\nIt is a parameter calculated from CheckAddress API that is based on Geocoding. It represents the accuracy of the address, and can assume these values:\n\nAccuracy | Description\n------------|-------------\n``95`` | Maximum address accuracy\n``75`` | Good address accuracy\n``60`` | Medium address accuracy\n``40`` | Approximate address accuracy\n\n**Verified**\n\nA boolean flag, returned by the GeoCoding validation, telling you\nwhether the address was confirmed to an **exact** location. It is `true`\nonly when GeoCoding resolves the address to a precise, rooftop-level\nmatch.\n\nWhen `Verified` is `false`, ShippyPro found nothing wrong with the\naddress but could **not** confirm the exact location (the match was\ninterpolated or approximate). The address is accepted as-is, but you\nshould double-check it before shipping. In this case address corrections\n(`Message` entries such as \"Wrong city\"/\"Wrong zip\" and the\ncorresponding `NewAddress` fields) are **not** applied, because\napproximate matches can incorrectly point to a neighbouring city/area.\nCorrections are only suggested when the match is verified.\n\n`Verified` is present only when the GeoCoding validation was actually\nperformed.\n", "tags": [ "Addresses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CheckAddress" }, "Params": { "$ref": "#/components/schemas/CheckAddressParams" } } } } } }, "responses": { "200": { "description": "Address validation result (inspect `Result`, `Accuracy` and `Message`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckAddressResponse" }, "examples": { "validAddress": { "summary": "Address confirmed to an exact location", "value": { "Result": "OK", "Message": [], "Suggestions": [], "Accuracy": 95, "Verified": true } }, "invalidAddress": { "summary": "Address accepted with corrections suggested", "value": { "Result": "OK", "Message": [ "Wrong city", "Wrong zip" ], "Suggestions": [], "NewAddress": { "street1": "Calle Ancha 12", "street2": "", "city": "MOTRIL", "state": "GR", "zip": "18600", "country": "ES", "administrativeAreaLevel1": "Andalucia", "administrativeAreaLevel2": "Granada", "administrativeAreaLevel3": "Motril" }, "Accuracy": 60, "Verified": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/IsResidentialAddress": { "post": { "operationId": "IsResidentialAddress", "summary": "IsResidentialAddress", "description": "``Address Validation``\n\nThis method is used to classify if the addresses provided are residential.\n\nWith the ShippyPro IsResidentialAddress API, you can automatically check if a shipping addresses is a residential address.\n\n๐Ÿ’ก Checking residential addresses allows you:\n\n- to know if a delivery address is a home;\n\n- reduce possible frauds and and parallel import of your products.\n\n**How it works**\n\nThe IsResidentialAddress API provides enable you to verify if an address is residential (a home) or not.\nTo avoid issues with the verification you should use a validated and well formed address.\nPlease check [CheckAddress](#v1/tag/addresses/POST/v1/CheckAddress) API method to understand how to get validate a validated address.\n\nIsResidentialAddress method response returns two parameters:\n\n**Result**\n\nOK if the call was successful, or NOK if the call was unsuccessful.\n\n**IsResidentialAddress**\n\nA boolean value that represents if the address is residential (true) or not (false).\n", "tags": [ "Addresses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "IsResidentialAddress" }, "Params": { "$ref": "#/components/schemas/IsResidentialAddressParams" } } } } } }, "responses": { "200": { "description": "Residential classification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsResidentialAddressResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/BookPickup": { "post": { "operationId": "BookPickup", "summary": "BookPickup", "description": "``Shipping Platform``\n\nThis method allows you to book a Pick-Up for all supported carriers with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Optimize your operations and fulfillment process booking the pick up at your time convenience.\n- Speed-up carrier pick-ups.\n\n๐Ÿ“Œ Dimension units are set to KG and CM.\n\n๐Ÿ“Œ For some Carriers ``orderIds`` is required!\n", "tags": [ "Pickup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "BookPickup" }, "Params": { "$ref": "#/components/schemas/BookPickupParams" } } } } } }, "responses": { "200": { "description": "Pickup booked (inspect `Result` and `ConfirmationID`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookPickupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPickups": { "post": { "operationId": "GetPickups", "summary": "GetPickups", "description": "``Shipping Platform``\n\nThis method returns the list of scheduled pickups for all supported carriers with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Optimize your operations and fulfillment process getting the scheduled pick up list.\n- Speed-up carrier pick-ups.\n\n๐Ÿ“Œ If you do not set ``OrderID`` and ``PickupID`` this API will return all of your pickups scheduled.\n", "tags": [ "Pickup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPickups" }, "Params": { "$ref": "#/components/schemas/GetPickupsParams" } } } } } }, "responses": { "200": { "description": "List of scheduled pickups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPickupsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CancelPickup": { "post": { "operationId": "CancelPickup", "summary": "CancelPickup", "description": "``Shipping Platform``\n\nThis method allows you to cancel a scheduled pickup for all supported carriers with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Optimize your operations and fulfillment process deleting a scheduled pick up.\n- Speed-up carrier pick-ups.\n", "tags": [ "Pickup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CancelPickup" }, "Params": { "$ref": "#/components/schemas/CancelPickupParams" } } } } } }, "responses": { "200": { "description": "Pickup cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPickupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPickupAvailability": { "post": { "operationId": "GetPickupAvailability", "summary": "GetPickupAvailability", "description": "``Shipping Platform``\n\nThis method allows you to retrieve Pick Up availability for all the supported carriers (FedEx and MyDHL are the only supported carriers right now) with a single API request.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Optimize your operations and fulfillment process choosing the pick-up ready time for a scheduled pick-up.\n- Speed up carrier pick-ups.\n\n๐Ÿ“Œ Dimension units are set to KG and CM.\n\n๐Ÿ“Œ You can filter this call for specific services by filling out the PickupCarriers field with CarrierName and CarrierID, which you can retrieve from the APIKEYS ShippyPro page.\n\nE.G ``PickupCarriers: [\"CarrierName|CarrierID\", \"CarrierName|CarrierID\"]``\n", "tags": [ "Pickup" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPickupAvailability" }, "Params": { "$ref": "#/components/schemas/GetPickupAvailabilityParams" } } } } } }, "responses": { "200": { "description": "Pickup availability windows and any per-carrier errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPickupAvailabilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetMarketplaces": { "post": { "operationId": "GetMarketplaces", "summary": "GetMarketplaces", "description": "``Shipping Platform``\n\nThis method returns all the Marketplaces IDs already connected to your ShippyPro account.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve connected Marketplace list and their IDs and Labels.\n\n- Retrieve active or inactive Marketplaces.\n", "tags": [ "Marketplaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetMarketplaces" }, "Params": { "$ref": "#/components/schemas/GetMarketplacesParams" } } } } } }, "responses": { "200": { "description": "List of connected marketplaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMarketplacesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetCarriers": { "post": { "operationId": "GetCarriers", "summary": "GetCarriers", "description": "``Shipping Platform``\n\nThis method allows you to get the list of connected carriers and their details in your ShippyPro account.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve connected carrier list.\n\n- Get **CarrierID** and other carrier details to use in API calls.\n\n- Get Carrier shipment services.\n", "tags": [ "Carriers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetCarriers" }, "Params": { "$ref": "#/components/schemas/GetCarriersParams" } } } } } }, "responses": { "200": { "description": "List of connected carriers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCarriersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetCarrierOptions": { "post": { "operationId": "GetCarrierOptions", "summary": "GetCarrierOptions", "description": "``Shipping Platform``\n\nThis method allows you to get the available Carrier options for a specific Carrier.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve the available carrier options for a carrier.\n- Use the retrieved carrier options in other API calls.\n\nFor more information on how setup a Carrier options click [here](https://help.shippypro.com/en/knowledge/articles/8812659-new-experience-how-can-i-add-carrier-options-to-my-shipments).\n\n๐Ÿ“Œ The recipient address is optional. Add it to also receive the carrier's Pick-Up & DropOff point options.\n", "tags": [ "Carriers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetCarrierOptions" }, "Params": { "$ref": "#/components/schemas/GetCarrierOptionsParams" } } } } } }, "responses": { "200": { "description": "Available carrier options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCarrierOptionsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetCarrierPackagesTypes": { "post": { "operationId": "GetCarrierPackagesTypes", "summary": "GetCarrierPackagesTypes", "description": "``Shipping Platform``\n\nThis method allows you to get the available carrier packages types.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve carrier predefined package type list.\n\n- Use the retrieved carrier packages in other API calls.\n", "tags": [ "Carriers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetCarrierPackagesTypes" }, "Params": { "$ref": "#/components/schemas/GetCarrierPackagesTypesParams" } } } } } }, "responses": { "200": { "description": "Available carrier package types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCarrierPackagesTypesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CreateManifest": { "post": { "operationId": "CreateManifest", "summary": "CreateManifest", "description": "``Shipping Platform``\n\nThis method allows you to create a Manifest file for the specified Order numbers with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Create a Manifest file for your orders.\n\nโš ๏ธ Note that the response attribute ``ManifestURL`` could be both string (if there is only one Manifest) or an array (if there are more than one).\n\nโš ๏ธ If another CreateManifest call for the same account is already running, this call returns the error ``MANIFEST_IN_PROGRESS`` after waiting up to 15 seconds. It is safe to retry after a few seconds. Concurrent CreateManifest calls for the same account are serialized, so sending one call with all the order ids is faster than firing several in parallel.\n", "tags": [ "Manifest" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CreateManifest" }, "Params": { "$ref": "#/components/schemas/CreateManifestParams" } } } } } }, "responses": { "200": { "description": "Manifest created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManifestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetManifest": { "post": { "operationId": "GetManifest", "summary": "GetManifest", "description": "``Shipping Platform``\n\nThis method allows you to get an already created Manifest document with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve an already created manifest document\n\nโš ๏ธ Note that the response attribute ``ManifestURL`` could be both string (if there is only one Manifest) or an array (if there are more than one).\n", "tags": [ "Manifest" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetManifest" }, "Params": { "$ref": "#/components/schemas/GetManifestParams" } } } } } }, "responses": { "200": { "description": "Manifest document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetManifestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/DeleteManifest": { "post": { "operationId": "DeleteManifest", "summary": "DeleteManifest", "description": "``Shipping Platform``\n\nThis method allows you to delete an already generated Manifest document with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Delete an already created manifest document.\n", "tags": [ "Manifest" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "DeleteManifest" }, "Params": { "$ref": "#/components/schemas/DeleteManifestParams" } } } } } }, "responses": { "200": { "description": "Manifest deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteManifestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CloseShipments": { "post": { "operationId": "CloseShipments", "summary": "CloseShipments", "description": "``Shipping Platform``\n\nThis method transmits your shipments to the carrier and closes the work day, as some carriers require before they will accept the parcels.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Confirm and transmit the day's shipments to a carrier.\n- Close a [Progressive Multiparcel](#v1/tag/shipments/POST/v1/Ship) shipment.\n- Retrieve the manifest the carrier produces at closeout, where it produces one.\n\n**When you need it**\n\nNot every carrier requires a closeout. Carriers that require it do not consider the shipments handed over until they have been transmitted, so the parcels are not expected at pickup until you call this method. Check whether yours requires it on the [carriers comparison map](https://www.shippypro.com/en/carriers-comparison-map/), or with your carrier representative.\n\n``CarrierName`` is the carrier whose shipments you are closing โ€” the same value you pass to [Ship](#v1/tag/shipments/POST/v1/Ship), listed at the bottom of the [API Keys page](https://www.shippypro.com/panel/apikeys.html) and returned by [GetCarriers](#v1/tag/carriers/POST/v1/GetCarriers). It is the only carrier parameter: one call covers every connection you hold to that carrier, and closing two different carriers takes two calls.\n\n**What comes back**\n\nThe call returns ``200`` even when the closeout does not succeed, so always inspect ``Result`` and ``ErrorMessage`` rather than the status code alone.\n\nWhere the carrier produces a manifest at closeout, ``ManifestNumber``, ``ManifestURL`` and ``AdditionalDocs`` carry it. ``ManifestURL`` is an empty array when no manifest was generated, which is not an error in itself. Manifests can also be created on their own with [CreateManifest](#v1/tag/manifest/POST/v1/CreateManifest) and fetched later with [GetManifest](#v1/tag/manifest/POST/v1/GetManifest).\n\n**Progressive Multiparcel**\n\nThis method is the closeout of a [Progressive Multiparcel](#v1/tag/shipments/POST/v1/Ship) shipment. The Ship calls only produce the labels; the carrier is told about the complete shipment here.\n\nโš ๏ธ **A group closes whole.** Naming one parcel of a progressive shipment in ``OrderIDS`` closes every parcel of its group, so listing a subset does not close only that subset. Call [VoidShipments](#v1/tag/orders/POST/v1/VoidShipments) on any parcel you do not want to send **before** closing โ€” otherwise the carrier will expect it.\n\nOmitting ``OrderIDS`` widens the call instead of narrowing it: it then takes every order for that carrier that has not been closed yet, going back one month, across all your receivers and connections. Re-closing is safe, since a parcel transmitted in an earlier closeout is skipped rather than sent again.\n\nParcels shipped after a closeout open a new group rather than joining the one just closed, so the next call confirms them as a separate shipment.\n\nA progressive multiparcel group accepts new parcels for 5 days (120 hours) from its first parcel, and the closeout closes every parcel of the group, including parcels shipped on different days. After the 5 days, later parcels go to a new group, and reaching 5 days does not close the earlier group: it still has to be closed with this call. Running it at the end of each working day is a good habit, and calling it more than once is fine. For a subset of carriers the closeout can instead be scheduled to run automatically, per carrier connection, from *Utilities โ†’ Task scheduler* in the ShippyPro application.\n\n๐Ÿ“Œ Not to be confused with [CloseMasterShipment](#v1/tag/orders/POST/v1/CloseMasterShipment), which closes a Bulk Shipping stream (currently MYDHLBBX only) around a master shipment ID that you create yourself with CreateMasterShipment.\n", "tags": [ "Manifest" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CloseShipments" }, "Params": { "$ref": "#/components/schemas/CloseShipmentsParams" } } } } } }, "responses": { "200": { "description": "Shipments transmitted (inspect `Result` / `ErrorMessage` for outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseShipmentsResponse" }, "examples": { "withManifest": { "summary": "Shipments closed, carrier produced a manifest", "value": { "Result": "OK", "ErrorMessage": "", "ManifestNumber": 1, "ManifestURL": [ "https://cdn.shippypro.com/manifests/manifest-u11n1-15332055452.pdf" ], "AdditionalDocs": [] } }, "withoutManifest": { "summary": "Shipments closed, carrier produced no manifest", "description": "`ManifestURL` is an empty array whenever the carrier does not generate\na manifest at closeout. The shipments are still transmitted.\n", "value": { "Result": "OK", "ErrorMessage": "", "ManifestURL": [], "AdditionalDocs": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/UploadPaperlessDocumentation": { "post": { "operationId": "UploadPaperlessDocumentation", "summary": "UploadPaperlessDocumentation", "description": "``Shipping Platform``\n\nElectronic Trade Documents (ETD) or Paperless customs is an automated international shipping solution that allows you to submit your customs documentation electronically so you no longer need to print and attach multiple copies to your shipments. Not all the carriers support paperless, please check [here](https://help.shippypro.com/en/knowledge/articles/8880574-new-experience-how-to-manage-your-etd-documents) if your carrier support it.\n\n๐Ÿ’ก This method gives you the ability to:\n\n- Upload custom documents for international shipments, you'll save both paper and time!\n\n- Automatically transmit custom documents as soon as your international shipping labels are created.\n\n### List of supported document types\n\nValue |Description\n----------------|-------------------\n``0``|Invoice (default)\n``1``|Air Waybill\n``2``|Proforma invoice\n``3``|Certificate of Origin\n``4``|Usmca Certificate of Origin\n``5``|Commercial invoice\n``6``|Customs declaration\n``99``|Other\n\n**Useful tips**\n\n๐Ÿ“Œ You need to make ETD through UploadPaperlessDocumentation call before making Ship call (or before sending the order from ShippyPro), or the ETD won't be linked to Ship call: TransactionID, Name, Country fields must match (case sensitive).\n\n๐Ÿ“Œ If you make a UploadPaperlessDocumentation API call with a TransactionID already present inside ShippyPro, it will be automatically be attached to your order if shipped within the next 24 hours.\n\n๐Ÿ“Œ UploadPaperlessDocumentation API can be used only once. Edit method API call cannot be employed with this specific call. This means that if you need to apply some changes on a Paperless document already generated, you should make a new UploadPaperlessDocumentation API call as well as a new Ship related to this new one.\n\n๐Ÿ“Œ On another hand, if you upload an X number of Paperless documents without any order inside To Ship section and then you create your shipments, all the ETDs from the last 24h will be attached.\n\n๐Ÿ“Œ In case you upload two ETDs with the same TransactionID and then you create the shipment, only the most recent file will be attached.\n", "tags": [ "Paperless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "UploadPaperlessDocumentation" }, "Params": { "$ref": "#/components/schemas/UploadPaperlessDocumentationParams" } } } } } }, "responses": { "200": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadPaperlessDocumentationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/DeletePaperlessDocumentation": { "post": { "operationId": "DeletePaperlessDocumentation", "summary": "DeletePaperlessDocumentation", "description": "``Shipping Platform``\n\nThis method allows you to delete unused Electronic Trade Documents\n(ETD / Paperless customs) that you previously uploaded with\n[UploadPaperlessDocumentation](#v1/tag/paperless/POST/v1/UploadPaperlessDocumentation),\nselecting them by the TransactionID or the recipient Name you supplied\nat upload time.\n\n๐Ÿ’ก This method gives you the ability to:\n\n- Delete the unused paperless documents linked to a TransactionID or a\n recipient Name, optionally narrowing by DocumentType.\n\nThe supported ``DocumentType`` values are the same as for\n[UploadPaperlessDocumentation](#v1/tag/paperless/POST/v1/UploadPaperlessDocumentation).\n\n**Useful tips**\n\n๐Ÿ“Œ You must provide at least one of ``TransactionID`` or ``Name`` (you\nmay provide both); if you provide neither, the call returns\n``INVALID_INPUT_DATA``. ``TransactionID`` matches documents uploaded for\nan order already present in ShippyPro. ``Name`` matches documents\nuploaded ahead of the order โ€” these are stored without a TransactionID\nand are addressed by the recipient Name you sent at upload (case\nsensitive). Pass ``DocumentType`` to delete only documents of that type;\nomit it to delete every matching unused document.\n\n๐Ÿ“Œ Only documents uploaded in the last 24 hours are eligible โ€” the same\nwindow in which an uploaded ETD can still be attached to a shipment.\n\n๐Ÿ“Œ Documents already used (attached to a shipped order) are never\ndeleted: they are reported under ``Skipped``. If every matching document\nis already used, the call returns the ``ETD_ALREADY_USED`` error.\n", "tags": [ "Paperless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "DeletePaperlessDocumentation" }, "Params": { "$ref": "#/components/schemas/DeletePaperlessDocumentationParams" } } } } } }, "responses": { "200": { "description": "Deletion outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePaperlessDocumentationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/UploadPaperlessPostShip": { "post": { "operationId": "UploadPaperlessPostShip", "summary": "UploadPaperlessPostShip", "description": "``Shipping Platform``\n\nElectronic Trade Documents (ETD) or Paperless customs is an automated international shipping solution that allows you to submit your customs documentation electronically so you no longer need to print and attach multiple copies to your shipments.\n\n๐Ÿ’ก This method gives you the ability to:\n\n- Upload custom documents for international shipments after the shipping label has been generated.\n\n### List of supported document types\n\nValue |Description\n----------------|-------------------\n``0``|Invoice (default)\n``1``|Air Waybill\n``2``|Proforma invoice\n``3``|Certificate of Origin\n``4``|Usmca Certificate of Origin\n``5``|Commercial invoice\n``6``|Customs declaration\n``99``|Other\n\n**Useful tips**\n\n๐Ÿ“Œ You need to make the UploadPaperlessPostShip call after making the Ship call setting PostShipmentETD at True.\n\n๐Ÿ“Œ UploadPaperlessPostShip API will immediately send the ETD documents to the carrier.\n\n๐Ÿ“Œ You can upload multiple documents in the same UploadPaperlessPostShip call.\n", "tags": [ "Paperless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "UploadPaperlessPostShip" }, "Params": { "$ref": "#/components/schemas/UploadPaperlessPostShipParams" } } } } } }, "responses": { "200": { "description": "Documents uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadPaperlessPostShipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CreateCrossBorderInvoice": { "post": { "operationId": "CreateCrossBorderInvoice", "summary": "CreateCrossBorderInvoice", "description": "``Shipping Platform``\n\nThis method allows you to generate an invoice specifically designed for customs declaration and transmit it to the allowed carriers with just one request.\n\n๐Ÿ’ก This Method gives you the ability to:\n\nGenerate Commercial or Proforma Invoice: This method enables the creation of a commercial or proforma invoice, which is required for cross-border shipments.\n\nTransmit Paperless Invoice: You can transmit the invoice directly to the carrier as an Electronic Trade Document (ETD), making it a paperless transaction.\n\nUseful tips\n\n๐Ÿ“Œ To transmit the invoice to the carrier as a paperless document, ensure that the UploadETD parameter is set to True when making the API call.\n\n๐Ÿ“Œ If the invoice needs to be created and transmitted to the carrier after the shipment is created, you should:\n\nMake the Ship call to create the shipment, ensuring that the PostShipmentETD flag is set to True.\n\nCall the CreateCrossBorderInvoice call\n", "tags": [ "Paperless" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CreateCrossBorderInvoice" }, "Params": { "$ref": "#/components/schemas/CreateCrossBorderInvoiceParams" } } } } } }, "responses": { "200": { "description": "Invoice created (Base64-encoded PDF returned in `CrossborderInvoice`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCrossBorderInvoiceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetOrder": { "post": { "operationId": "GetOrder", "summary": "GetOrder", "description": "``Shipping Platform``\n\nThis method retrieves order/shipment details with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve shipment labels\n- Retrieve order details as carrier name, tracking number and source store.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetOrder" }, "Params": { "$ref": "#/components/schemas/GetOrderParams" } } } } } }, "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/ArchiveOrders": { "post": { "operationId": "ArchiveOrders", "summary": "ArchiveOrders", "description": "``Shipping Platform``\n\nThis method archives a shipped order with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Archive a shipped order.\n- Clean the ShippyPro shipped view from unnecessary orders.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "ArchiveOrders" }, "Params": { "$ref": "#/components/schemas/ArchiveOrdersParams" } } } } } }, "responses": { "200": { "description": "Orders archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/UpdateOrders": { "post": { "operationId": "UpdateOrders", "summary": "UpdateOrders", "description": "``Shipping Platform``\n\nThis method allows you to send shipment info to the marketplaces and mark the order as shipped with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n - Send order shipment info to your marketplaces and mark the orders as shipped\n - Complete the marketplace orders fullfillment process.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "UpdateOrders" }, "Params": { "$ref": "#/components/schemas/UpdateOrdersParams" } } } } } }, "responses": { "200": { "description": "Orders updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/PutOrder": { "post": { "operationId": "PutOrder", "summary": "PutOrder", "description": "``Shipping Platform``\n\nThis method allows you to create your Orders inside ShippyPro and then ship them.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Import orders to be shipped inside ShippyPro\n\nIn order to upload orders, you must first [configure a Marketplace](https://www.shippypro.com/panel/marketplace.html) in ShyppyPro, retrieve its ID from the marketplace page to then fill the APIOrdersID method request paramenter.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "PutOrder" }, "Params": { "$ref": "#/components/schemas/PutOrderParams" } } } } } }, "responses": { "200": { "description": "Order created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/VoidShipments": { "post": { "operationId": "VoidShipments", "summary": "VoidShipments", "description": "``Shipping Platform``\n\nThis method allows you to void your previously generated shipment inside ShippyPro.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Void created shipments inside ShippyPro\n\nThis Method cancel an order inside ShippyPro. Please note that not all the carriers support to void a shipment, please check [here](https://www.shippypro.com/en/carriers-comparison-map/) if your carrier supports it.\n\n๐Ÿ“Œ If you'd like to cancel a shipment for a Carrier which is not supporting void, you'll need to proceed directly from Carrier's website.\nThis way it will be automatically removed from ShippyPro as well as from Carrier's server and, therefore, cancelled.\n\n๐Ÿ“Œ In case you need to look for it in the future, you'll still be able to find it by entering the Order ID in ShippyPro Global Search feature.\n\n๐Ÿ“Œ For a [Progressive Multiparcel](#v1/tag/shipments/POST/v1/Ship) shipment, voiding is the **only** way to keep an already-shipped parcel out of the closeout, and it must happen **before** you call [CloseShipments](#v1/tag/manifest/POST/v1/CloseShipments). Naming one parcel of a group in ``OrderIDS`` closes the whole group, so a parcel left un-voided is communicated to the carrier and expected by it. Once the shipment is closed it can no longer be amended this way.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "VoidShipments" }, "Params": { "$ref": "#/components/schemas/VoidShipmentsParams" } } } } } }, "responses": { "200": { "description": "Void outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidShipmentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetLabelUrl": { "post": { "operationId": "GetLabelUrl", "summary": "GetLabelUrl", "description": "``Shipping Platform``\n\nThis method allows you to get the order labels and tracking data with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve order labels (URL and label raw data).\n- Retrieve Tracking Number, Tracking Status and Tracking Carrier.\n\nโš ๏ธ Note! The data type of the response attribute LabelURL could be both an array or a string.\n- it's an empty array if the order is in error,[].\n- it's a string if the order has one label, \"label-url\".\n- it's an array of strings if the order has more than one label, [\"label-url-1\", \"label-url-2\", ...].\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetLabelUrl" }, "Params": { "$ref": "#/components/schemas/GetLabelUrlParams" } } } } } }, "responses": { "200": { "description": "Label URLs, raw label data and tracking information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLabelUrlResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPendingOrders": { "post": { "operationId": "GetPendingOrders", "summary": "GetPendingOrders", "description": "``Shipping Platform``\n\nThis method allows you to get not yet shipped order list for 60+ marketplace with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve all the orders not yet shipped.\n- Retrieve unshipped order details.\n\n**How to test**\n\n- In order to test this method you need to connect at least a sales channel/marketplace.\n- If you are using **API Orders** as sales channel you need to retrieve [API Orders ID](https://help.shippypro.com/en/knowledge/articles/4086929-how-to-activate-api-orders-folder-in-to-ship-section) and use it in the PutOrder call when you are putting the order.\n\nThe Excel Manual Shipments and Ship API Method, don't allows to import order details as put put order.\n\n**MarketPlace Order Item Attributes**\n\nFor Shopify and Maxpho, the method can retrieve also order items attributes, if ``IncludeItemsAttributes`` is set to true.\nAnyway for Magento orders an items mapping is needed in order to retrieve items attributes.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPendingOrders" }, "Params": { "$ref": "#/components/schemas/GetPendingOrdersParams" } } } } } }, "responses": { "200": { "description": "List of pending (not yet shipped) orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPendingOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetShippedOrders": { "post": { "operationId": "GetShippedOrders", "summary": "GetShippedOrders", "description": "``Shipping Platform``\n\nThis method allows you to get shipped (label generated) order list with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Retrieve all the shipped orders.\n- Get shipped orders data.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetShippedOrders" }, "Params": { "$ref": "#/components/schemas/GetShippedOrdersParams" } } } } } }, "responses": { "200": { "description": "List of shipped orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShippedOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/DeletePendingOrder": { "post": { "operationId": "DeletePendingOrder", "summary": "DeletePendingOrder", "description": "``Shipping Platform``\n\nThis method allows you to delete a not yet shipped order with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Delete an unshipped order.\n\nโš ๏ธ You have to set at least one markeplace ID to get its APIOrdersID to fill the request method parameter.\n\nThe result is OK if the call was successful, or NOK if the call was unsuccessful.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "DeletePendingOrder" }, "Params": { "$ref": "#/components/schemas/DeletePendingOrderParams" } } } } } }, "responses": { "200": { "description": "Deletion outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePendingOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/IsPendingOrder": { "post": { "operationId": "IsPendingOrder", "summary": "IsPendingOrder", "description": "``Shipping Platform``\n\nThis method allows you to verify if an order not yet shipped with the same API call.\n\nThis method returns true if the order has not yet been shipped, or if it has been shipped but the shipment failed.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Check if an order is shipped.\n\nYou can call the [GetMarketPlaces](#v1/tag/marketplaces/POST/v1/GetMarketplaces) API method to retrieve your connected Market Place names.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "IsPendingOrder" }, "Params": { "$ref": "#/components/schemas/IsPendingOrderParams" } } } } } }, "responses": { "200": { "description": "Whether the order is still pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsPendingOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/EditPendingOrders": { "post": { "operationId": "EditPendingOrders", "summary": "EditPendingOrders", "description": "``Shipping Platform``\n\nThis method allows you to edit orders not shipped yet\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Update the carrier options for unshipped orders\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "EditPendingOrders" }, "Params": { "$ref": "#/components/schemas/EditPendingOrdersParams" } } } } } }, "responses": { "200": { "description": "Per-order edit outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditPendingOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/PutShippedOrder": { "post": { "operationId": "PutShippedOrder", "summary": "PutShippedOrder", "description": "``Shipping Platform``\n\nThis method allows you to add external Orders already been shipped inside your ShippyPro profile.\nBy doing so, you can use our Easy Return, Tracking Solver, Optimizer and Invoice Analysis features without generating the shipping labels via ShippyPro.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Add an already shipped order in ShyppyPro to benefit of post shipping ShippyPro features as tracking or returns.\n- Use our Easy Return, Tracking Solver, Optimizer and Invoice Analysis features without generating the shipping labels via ShippyPro.\n- Link the new order to an existing one in the to-ship section.\n\n**How to use**\n\nIn order to import shipped order in ShippyPro with this method, you need to activate API-Folder and get its APIOrdersID.\nFollow [this guide](https://help.shippypro.com/en/knowledge/articles/4086929-how-to-activate-api-orders-folder-in-to-ship-section) to actiate API-Folder in your ShippyPro account.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "PutShippedOrder" }, "Params": { "$ref": "#/components/schemas/PutShippedOrderParams" } } } } } }, "responses": { "200": { "description": "Order imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutShippedOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPOD": { "post": { "operationId": "GetPOD", "summary": "GetPOD", "description": "``Shipping Platform``\n\nThis method allows you to get Proof Of Delivery for delivered shipments with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get the carrier shipment proof of delivery document.\n- Certify to your customers that the shipment has been delivered.\n- Resolve customers claims or inquiries.\n\n๐Ÿ“Œ Please note that not all the carriers support POD Documentation, please check [here](https://www.shippypro.com/en/carriers-comparison-map/) if your carrier supports it.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPOD" }, "Params": { "$ref": "#/components/schemas/GetPODParams" } } } } } }, "responses": { "200": { "description": "Proof of delivery document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPODResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPODDocument": { "post": { "operationId": "GetPODDocument", "summary": "GetPODDocument", "description": "``Shipping Platform``\n\nThis method allows you to get a PDF document that includes the carrier Proof Of Delivery together with the related shipment details (such as tracking number, delivery date and carrier) for delivered shipments with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get a single PDF document containing both the carrier proof of delivery and the shipment details.\n\n๐Ÿ“Œ The ``Result`` field reports whether the document includes the proof of delivery signature:\n- ``OK``: the document was generated with the POD signature.\n- ``PARTIAL_OK``: the document was generated without a POD signature (the carrier did not provide one).\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPODDocument" }, "Params": { "$ref": "#/components/schemas/GetPODDocumentParams" } } } } } }, "responses": { "200": { "description": "Combined POD and shipment details PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPODDocumentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetDetailedPricing": { "post": { "operationId": "GetDetailedPricing", "summary": "GetDetailedPricing", "description": "``Shipping Platform``\n\nThis method allows you to get detailed estimated pricing calculated of one order with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get detailed pricing for an existing order.\n\n๐Ÿ“Œ The method is only available for carriers without live rates and does requires:\n\n- That the zones and the pricing information should be configured in the ShippyPro account;\n- A GetRates API call before to get pricing information (see below);\n- GetRates information should be passed in the ship call to create the order, get the order id, and call the GetDetailedPricing.\n\n*Price Information from GetRates to be passed in the Ship call*\n\n```js\n\"zone_name\": \"Italy\",\n\"weight_range\": \"0-500\",\n\"detailed_pricing\": [\n {\n \"type\": \"tariff\",\n \"price\": 10,\n \"desc\": \"Tariff\"\n }\n]\n```\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetDetailedPricing" }, "Params": { "$ref": "#/components/schemas/GetDetailedPricingParams" } } } } } }, "responses": { "200": { "description": "Detailed pricing breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDetailedPricingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CreateInvoice": { "post": { "operationId": "CreateInvoice", "summary": "CreateInvoice", "description": "``Shipping Platform``\n\nThis method allows you to generate and get Order summary or invoice for one or more Orders with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Generate Order summary or invoice.\n\n๐Ÿ“Œ Each Order to include must be a different object in the \"Documents\" array.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CreateInvoice" }, "Params": { "$ref": "#/components/schemas/CreateInvoiceParams" } } } } } }, "responses": { "200": { "description": "Generated document(s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/MarkOrdersAsPrinted": { "post": { "operationId": "MarkOrdersAsPrinted", "summary": "MarkOrdersAsPrinted", "description": "``Shipping Platform``\n\nThis method allows you to mark orders as printed with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Mark orders as printed so that the registration date and time values are calculated.\n- Mark orders as printed and processable from your cronjob.\n\n๐Ÿ“Œ Printing labels using API integration does not permit to know if an order has been really printed on by your printers.\nSo, if you use cronjobs that acts on printed orders, eg. Archive Orders or Updated Orders, you need to mark them as printed, to make them processable by cronjobs.\nAnyway cronjobs will process orders marked as printed based on their own schedule that you specify in ShippyPro cronjob section.\nIf you need more info on how cronjob works, please check our [cronjob help guide](https://help.shippypro.com/en/knowledge/articles/3349602-how-cron-jobs-works).\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "MarkOrdersAsPrinted" }, "Params": { "$ref": "#/components/schemas/MarkOrdersAsPrintedParams" } } } } } }, "responses": { "200": { "description": "Orders marked as printed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkOrdersAsPrintedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetShipmentsReport": { "post": { "operationId": "GetShipmentsReport", "summary": "GetShipmentsReport", "description": "``Shipping Platform``\n\nThis method allows you to get the list of shipments (and returns) in the specified timeframe with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get the list of shipments and returns in the specified timeframe.\n- Generate shipments and returns report on demand.\n- The return field is true for returns shipments generated manually, via the Easy Return module and through the Return Label Combination. This endpoint does not include returns generated via Return Label in the Box.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetShipmentsReport" }, "Params": { "$ref": "#/components/schemas/GetShipmentsReportParams" } } } } } }, "responses": { "200": { "description": "List of shipments (and returns) in the timeframe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShipmentsReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetReturnsReport": { "post": { "operationId": "GetReturnsReport", "summary": "GetReturnsReport", "description": "``Return``\n\nThis method allows you to get the list of returns in the specified timeframe with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get a list of returns.\n- Generate returns report on demand.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetReturnsReport" }, "Params": { "$ref": "#/components/schemas/GetReturnsReportParams" } } } } } }, "responses": { "200": { "description": "List of returns in the timeframe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReturnsReportResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CreateMasterShipment": { "post": { "operationId": "CreateMasterShipment", "summary": "CreateMasterShipment", "description": "``Shipping Platform``\n\nThis method allows you to obtain a new Master Shipment Identifier in order to initialize a Bulk Shipping request with a carrier that supports it.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Obtain a new Master Shipment Identifier.\n- Pass the Master Shipment Identifier as Carrier Option with a Ship request.\n\n๐Ÿ“Œ A Master Shipment Identifier (MasterShipmentID) can be obtained through API `CreateMasterShipment` solely by passing a Carrier that actively supports Bulk Shipping. Bulk Shipping allows customers to consolidate multiple shipments with different destinations, typically within the same country, but handled by the courier at a common sorting center, and therefore sharing the same intermediate stop. Orders are first dispatched to an import center as a whole, and later delivered to their individual final destinations.\n\nโš ๏ธ Bulk Shipping is currently available only with the **MYDHLBBX** carrier.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CreateMasterShipment" }, "Params": { "$ref": "#/components/schemas/CreateMasterShipmentParams" } } } } } }, "responses": { "200": { "description": "Master Shipment Identifier created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMasterShipmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/CloseMasterShipment": { "post": { "operationId": "CloseMasterShipment", "summary": "CloseMasterShipment", "description": "``Shipping Platform``\n\nThis method allows for the closure of a Bulk Shipping stream. Bulk Shipping is available only for a small selection of couriers. The Bulk Shipping process begins with a request to the CreateMasterShipment endpoint, which returns a Master Shipment ID. This ID is used for all subsequent Ship calls using a dedicated carrier option. Upon completion of the shipments, the Bulk Shipping stream must be formally closed through a call to the CloseMasterShipment endpoint, which handles the finalization and grouping of the previous shipments according to the specifications of the individual courier used.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Group all previous Bulk Shipping shipments.\n- Finalize the process and inform the courier that the shipment is ready for pickup\n\n๐Ÿ“Œ A Master Shipment Identifier (MasterShipmentID) can be obtained through API `CreateMasterShipment` solely by passing a Carrier that actively supports Bulk Shipping. Bulk Shipping allows customers to consolidate multiple shipments with different destinations, typically within the same country, but handled by the courier at a common sorting center, and therefore sharing the same intermediate stop. Orders are first dispatched to an import center as a whole, and later delivered to their individual final destinations.\n\nโš ๏ธ Bulk Shipping is currently available only with the **MYDHLBBX** carrier.\n\n๐Ÿ“Œ This API method is heavily based on API Ship, thus it shares almost the same request parameters list. There are minor differences that should be accounted for. Please refer to the table below and API Ship documentation.\n\n๐Ÿ“Œ This list solely highlights differences between API CloseMasterShipment and Ship. Every other parameter available with Ship can also be used with this method.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "CloseMasterShipment" }, "Params": { "$ref": "#/components/schemas/CloseMasterShipmentParams" } } } } } }, "responses": { "200": { "description": "Master shipment closed (inspect `Status` / `ErrorMessage` for outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseMasterShipmentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetPrinters": { "post": { "operationId": "GetPrinters", "summary": "GetPrinters", "description": "``Shipping Platform``\n\nThis method allows you to get the list of connected printer in your shippypro account.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Get the list of the all ShippyPro connected printer.\n- Get the list of connected printer to a specific computer.\n- Find a printer to print a label with.\n", "tags": [ "Printing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetPrinters" }, "Params": { "$ref": "#/components/schemas/GetPrintersParams" } } } } } }, "responses": { "200": { "description": "List of connected printers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPrintersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/PrintOrder": { "post": { "operationId": "PrintOrder", "summary": "PrintOrder", "description": "``Shipping Platform``\n\nThis method allows you to print Orders labels with to ShippyPro printer with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Print orders labels with a ShippyPro connected printer.\n", "tags": [ "Printing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "PrintOrder" }, "Params": { "$ref": "#/components/schemas/PrintOrderParams" } } } } } }, "responses": { "200": { "description": "Order sent to the printer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintOrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/PrintOrderBySKU": { "post": { "operationId": "PrintOrderBySKU", "summary": "PrintOrderBySKU", "description": "``Shipping Platform``\n\nThis method allows you to print Orders labels specifying an item SKU with a ShippyPro printer with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\nPrint orders labels with a ShippyPro connected printer saerching for an item SKU in your orders.\n", "tags": [ "Printing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "PrintOrderBySKU" }, "Params": { "$ref": "#/components/schemas/PrintOrderBySKUParams" } } } } } }, "responses": { "200": { "description": "Print-by-SKU outcome with printed, missing and acknowledged items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintOrderBySKUResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetDropOffPoints": { "post": { "operationId": "GetDropOffPoints", "summary": "GetDropOffPoints", "description": "``Checkout``\n\nThis method allows you to get all the nearest **Pick-Up & DropOff (PUDO)** points for all [supported carriers](https://www.shippypro.com/carrier-shipping-features.html) with the same API call.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Offer to your customers Pick-Up & DropOff (PUDO) points option as delivery method, showing Pick-Up & DropOff (PUDO) points for all your carriers at checkout on a customizable map.\n\n- Offer PUDOs as a Return Option.\n\n- Delight your customers offering experiences offering a next level shipping experience and reducing CO2 emissions.\n\n- Increase store conversion rate giving ability to display a map to customers where to choose nearest Pick-Up & DropOff (PUDO) points.\n\n- Reduce shipment costs of undeliverable shipments.\n\n**Response behavior:**\n\n- ``Result``: ``OK`` when all carriers returned successfully. ``PARTIAL_OK`` when some carriers failed (see ``Warnings``). ``NOK`` on request-level errors (e.g. missing required parameters).\n- ``Warnings``: *(optional)* Present only when ``Result`` is ``PARTIAL_OK``. An object keyed by carrier name with the value ``service_unavailable``, indicating our service could not fetch drop-off points for that carrier. The carrier will be **absent** from ``Points``. If a carrier legitimately has no nearby points, it will appear in ``Points`` with an empty array and no warning.\n\n**Note:** You must provide **either** ``city``/``zip``/``country`` **or** ``lat``/``lng`` to specify the location. Both sets are individually optional, but at least one complete set must be provided.\n", "tags": [ "Dropoff Points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetDropOffPoints" }, "Params": { "$ref": "#/components/schemas/GetDropOffPointsParams" } } } } } }, "responses": { "200": { "description": "Drop-off points grouped by carrier (inspect `Result` for per-request outcome)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDropOffPointsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetDropOffInfo": { "post": { "operationId": "GetDropOffInfo", "summary": "GetDropOffInfo", "description": "``Checkout``\n\nThis method allows you to obtain detailed information about a **Pick-Up & DropOff (PUDO)** point, starting from its pointId.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Offer to your customers Pick-Up & DropOff (PUDO) points option as delivery method, showing Pick-Up & DropOff (PUDO) points for all your carriers at checkout on a customizable map.\n\n- Offer PUDOs as a Return Option.\n\n- Delight your customers and optimize the delivery, offering more information about PUDO points, as operating hours and contacts.\n", "tags": [ "Dropoff Points" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetDropOffInfo" }, "Params": { "$ref": "#/components/schemas/GetDropOffInfoParams" } } } } } }, "responses": { "200": { "description": "Detailed drop-off point information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDropOffInfoResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetLoginToken": { "post": { "operationId": "GetLoginToken", "summary": "GetLoginToken", "description": "``Multi-level``\n\nThis method returns the access token to our platform for one user.\n", "tags": [ "Whitelabels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetLoginToken" }, "Params": { "$ref": "#/components/schemas/GetLoginTokenParams" } } } } } }, "responses": { "200": { "description": "Login token URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLoginTokenResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/RegisterNewUser": { "post": { "operationId": "RegisterNewUser", "summary": "RegisterNewUser", "description": "``Multi-level``\n\nThis method registers a new user on our platform.\n", "tags": [ "Whitelabels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "RegisterNewUser" }, "Params": { "$ref": "#/components/schemas/RegisterNewUserParams" } } } } } }, "responses": { "200": { "description": "User registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterNewUserResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/BlockUser": { "post": { "operationId": "BlockUser", "summary": "BlockUser", "description": "``Multi-level``\n\nThis method allows you to block a User.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Block a User.\n", "tags": [ "Whitelabels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "BlockUser" }, "Params": { "$ref": "#/components/schemas/BlockUserParams" } } } } } }, "responses": { "200": { "description": "User blocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockUserResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/UnblockUser": { "post": { "operationId": "UnblockUser", "summary": "UnblockUser", "description": "``Multi-level``\n\nThis method allows you to unblock a User.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Unblock a User.\n", "tags": [ "Whitelabels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "UnblockUser" }, "Params": { "$ref": "#/components/schemas/UnblockUserParams" } } } } } }, "responses": { "200": { "description": "User unblocked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockUserResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/GetCustomers": { "post": { "operationId": "GetCustomers", "summary": "GetCustomers", "description": "``Multi-level``\n\nThis method returns the customer list\n", "tags": [ "Whitelabels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "GetCustomers" }, "Params": { "$ref": "#/components/schemas/GetCustomersParams" } } } } } }, "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomersResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/Ping": { "post": { "operationId": "Ping", "summary": "Ping", "description": "``Shipping Platform``\n\nThis method is needed for checking the connection between your systems and the ShippyPro API.\n", "tags": [ "Monitoring" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "Method", "Params" ], "properties": { "Method": { "type": "string", "const": "Ping" }, "Params": { "$ref": "#/components/schemas/PingParams" } } } } } }, "responses": { "200": { "description": "Connection is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "webhooks": { "TrackingUpdate": { "post": { "operationId": "TrackingUpdateWebhook", "summary": "Tracking Update", "description": "``Tracking System``\n\nThis webhook gives you the ability send real time shipments tracking event to your store with the same webhook.\nYour store must support webhook in order to get the tracking updates.\n\n๐Ÿ’ก This webhook gives you the ability to:\n\n- Delight your customers with realtime shipment tracking events.\n- Reducing customer center enquiries/cost, increase CSAT and increase delivery success rate.\n- Reducing on hold shipment costs, your customer will be always updated about shipments status.\n\n**Estimated Delivery Date**\n\nThe estimated dalivery date **is returned only for carriers that supports Live Rates**.\nTo know which carrier support Live Rates and then the Estimated Delivery Date please check out carrier comparison map [here](https://www.shippypro.com/en/carriers-comparison-map/).\n\nAnyway, ShippyPro gives you the ability to manually set the delivery time for carriers that do not support live rates in the Carrier Connection Price page.\nIf these values are set, ShyppyPro will calculate the Estimated Delivery Date, and if values are not set, the Estimated Delivery Date will be returned as 0.\nFor more information on how to manually set Delivery Time, please check [here](https://help.shippypro.com/en/knowledge/articles/3339351-how-to-set-carrier-rates).\n\n**Tracking Code Values**\n\nTo simplify your work, we associated each carrier tracking statuses with these simple ShippyPro six shipments statuses.\nThese are the possible ShippyPro tracking code values.\n\nCode | Description\n------------|-------------\n``0`` | Order In Preparation\n``1`` | Info Received\n``2`` | In Transit\n``3`` | Out for Delivery\n``4`` | Missed Delivery\n``5`` | Exception\n``6`` | Delivered\n\n**Extended Tracking Statuses**\n\nEvery tracking update is additionally mapped to an extendedCode, representing a more granular status.\n\n### Extended Tracking Statuses\nExtended Code | Description\n------------|-------------\n``1000`` | Info Received\n``2000`` | In transit\n``2100`` | Dropped by customer\n``2200`` | Collected by carrier\n``2300`` | Carrier handling\n``2310`` | Arrived at terminal/hub\n``2320`` | Processing at terminal/hub\n``2330`` | Departed from terminal/hub\n``2400`` | Customs Clearance\n``2500`` | Delivery planned\n``3000`` | Out for Delivery\n``3100`` | Delivery in progress\n``3200`` | Available for pickup at PUDO/Facility\n``4000`` | Failed Attempt\n``5000`` | Generic Exception\n``5100`` | Transit Disruptions\n``5110`` | Delayed\n``5120`` | External causes\n``5200`` | Operational Issues\n``5210`` | Misrouted\n``5220`` | Pickup not possible\n``5230`` | On Hold\n``5300`` | Parcel Exception\n``5310`` | Exceeded dimensions or weight\n``5320`` | Damaged\n``5330`` | Lost\n``5340`` | Destroyed\n``5400`` | Address Discrepancies\n``5410`` | Insufficient address information\n``5420`` | Wrong address information\n``5500`` | Customs and Documentation\n``5510`` | Customs-related issues\n``5520`` | Missing documents\n``5600`` | Sender/Recipient-Related Events\n``5610`` | Recipient exception\n``5620`` | Sender exception\n``5630`` | Returning to sender\n``5640`` | Returned to sender\n``5700`` | Carrier Actions\n``5710`` | Carrier asks to be contacted\n``5720`` | Change to delivery\n``5730`` | Other Carrier Exception\n``6000`` | Delivered\n``6900`` | Manually Marked as Delivered\n``9999`` | Not mapped\n\n**Update Frequency**\n\nIn order to have a regular tracking status update on shipments, ShippyPro needs to inquiry carriers' APIs periodically.\nThe update frequency is different for each carrier and optimized to have tracking data as much updated as possible, without exceeding carrierโ€™s API throttling limits.\nHence you may receive webhooks with a certain delay on the carrier tracking event and, in case multiple events happen within the same updating timeframe, only the latest will be notified via webhook.\n", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingUpdateEvent" } } } }, "responses": { "200": { "description": "OK" } } } }, "OrderShipped": { "post": { "operationId": "OrderShippedWebhook", "summary": "Order Shipped", "description": "``Shipping Platform``\n\nThis webhook gives you the ability send real time shipments and label creation event including return shipments, to your system with the same webhook.\nYour system must support webhook in order to get the order shipped events.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Inform and delight your customers with realtime labels creation and shipments confirmation events including returns.\n- Reducing customer center enquiries/cost, increase CSAT and increase delivery success rate.\n- Trigger an update to your system when an order is shipped or returned with its generated label.\n", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderShippedEvent" } } } }, "responses": { "200": { "description": "OK" } } } }, "OrderError": { "post": { "operationId": "OrderErrorWebhook", "summary": "Order Error", "description": "``Shipping Platform``\n\nThis webhook gives you the ability send real time order error events and message to your store with the same webhook.\nYour store must support webhook in order to get the tracking updates.\n\n๐Ÿ’ก This Method gives you the ability to:\n\n- Inform your team with realtime label creation and shipment error events.\n- Improve and speedup order problem solving activities.\n- Reducing customer center enquiries/cost, increase CSAT and increase delivery success rate.\n- Trigger an update to your system when an order shipment error occur.\n", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderErrorEvent" }, "example": { "Event": "ORDER_ERROR", "OrderID": "191252", "TransactionID": "ORDER2365", "ErrorMessage": "Street too long", "ErrorType": { "code": "ADDRESS_INVALID", "name": "Invalid address", "typeDescription": "The recipient address was rejected by the carrier." }, "ErrorSuggestion": { "errorDescription": "The recipient street exceeds the maximum length accepted by the carrier.", "solution": "Shorten the street field and generate the label again.", "links": [ "https://help.shippypro.com/en/knowledge/api" ] } } } } }, "responses": { "200": { "description": "OK" } } } }, "ReturnLabelInTheBoxTrackingUpdate": { "post": { "operationId": "ReturnLabelInTheBoxTrackingUpdateWebhook", "summary": "Return Label in the Box Tracking Update", "description": "``Return``\n\n\nThis webhook gives you the ability receive real time tracking events for the Return Label in the Box process to your store with the same webhook.\nYour store must support webhook in order to get the tracking updates.\n\n**Tracking Code Values**\n\nTo simplify your work, we associated each carrier tracking statuses with these simple ShippyPro six shipments statuses.\nThese are the possible ShippyPro tracking code values.\n\nCode | Description\n------------|-------------\n``1`` | Info Received\n``2`` | In Transit\n``3`` | Out for Delivery\n``4`` | Missed Delivery\n``5`` | Exception\n``6`` | Delivered\n\n**Update Frequency**\n\nIn order to have a regular tracking status update on shipments, ShippyPro needs to inquiry carriers' APIs periodically.\nThe update frequency is different for each carrier and optimized to have tracking data as much updated as possible, without exceeding carrierโ€™s API throttling limits.\nHence you may receive webhooks with a certain delay on the carrier tracking event and, in case multiple events happen within the same updating timeframe, only the latest will be notified via webhook.\n", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnLabelInTheBoxTrackingUpdateEvent" } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication with your ShippyPro API Key.\n\nSend the API Key as the token.\n\nSee the **Authentication** section for more information.\n" } }, "schemas": { "Address": { "type": "object", "description": "A postal address (used for both sender and recipient).", "properties": { "name": { "type": "string", "example": "John Doe" }, "company": { "type": "string", "example": "" }, "street1": { "type": "string", "example": "123 Main St" }, "street2": { "type": "string", "example": "" }, "city": { "type": "string", "example": "Park City" }, "state": { "type": "string", "example": "UT" }, "zip": { "type": "string", "example": "84060" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "US" }, "phone": { "type": "string", "example": "5551231234" }, "email": { "type": "string", "format": "email", "example": "johndoe@gmail.com" } } }, "ShipParams": { "type": "object", "required": [ "to_address", "from_address", "parcels", "TransactionID", "ContentDescription", "CarrierName", "CarrierService", "CarrierID" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels included in the shipment.", "items": { "type": "object", "properties": { "length": { "description": "Parcel Length", "type": "number", "example": 5 }, "width": { "description": "Parcel width", "type": "number", "example": 5 }, "height": { "description": "Parcel height", "type": "number", "example": 5 }, "weight": { "type": "number", "example": 10 }, "dimension_unit": { "type": "string", "description": "Unit of measurement for dimensions: \"CM\" (default) or \"IN\".", "example": "CM" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight: \"KG\" (default), \"LB\", \"OZ\".", "example": "KG" }, "package": { "type": "integer", "description": "Carrier predefined package type; use the `value` attribute\nobtained through the GetCarrierPackagesTypes method.\n", "example": 1 }, "Attributes": { "type": "object", "properties": { "parcelID": { "type": "string", "example": "123456" }, "parcelType": { "type": "string", "example": "Box" } } } } } }, "TotalValue": { "type": "string", "description": "Declared value with currency, e.g. `\"123 EUR\"`. Required for international shipments. The only accepted punctuation is `.` before the decimal digits; any other punctuation causes an error.", "example": "123 EUR" }, "TransactionID": { "description": "Your internal reference order number", "type": "string", "maxLength": 255, "example": "ORDER2365" }, "MarketplaceID": { "description": "Your Marketplace ID", "type": "integer", "example": 1 }, "MarketplacePlatform": { "description": "The name of the marketplace to connect", "type": "string", "maxLength": 255, "example": "Amazon" }, "ContentDescription": { "type": "string", "maxLength": 255, "description": "Description of the content. Does not accept the backslash character;\nincluding one may cause errors or data processing problems.\n", "example": "Milk" }, "Insurance": { "description": "Insurance value (default: 0)", "type": "number", "example": 0 }, "InsuranceCurrency": { "description": "Insurance currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "CashOnDelivery": { "description": "Cash on delivery value (default: 0)", "type": "number", "example": 0 }, "CashOnDeliveryCurrency": { "description": "Cash on delivery currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "CashOnDeliveryType": { "description": "Cash on delivery type, 0 = Cash (default), 1 = Cashier's check, 2 = Check, 3 = All Payment Methods", "type": "integer", "enum": [ 0, 1, 2, 3 ], "example": 0 }, "CarrierName": { "description": "Selected rate Carrier Name, as reported in the GetRates", "type": "string", "example": "MyDHL" }, "CarrierService": { "description": "Selected rate Carrier Service, as reported in the GetRates", "type": "string", "example": "EXPRESS DOMESTIC" }, "CarrierID": { "description": "Selected rate CarrierID, as reported in the [GetRates](#v1/tag/shipments/POST/v1/GetRates)", "type": "integer", "example": 23 }, "OrderID": { "description": "Selected rate OrderID, as reported in the GetRates", "type": "string", "example": "" }, "RateID": { "description": "Selected rate RateID, as reported in the GetRates", "type": "string", "example": "14922625303744" }, "Incoterm": { "description": "Shipment incoterm: DAP, DDP, or EXW. For cross borders shipments the default value would be DAP in case it's not specified in the request differently", "type": "string", "enum": [ "DAP", "DDP", "EXW" ], "example": "DAP" }, "BillAccountNumber": { "type": "string", "description": "Bill the shipment to a third-party account number. Required โ€” and\nshould only be filled โ€” when the Incoterm is EXW.\n", "example": "" }, "PaymentMethod": { "description": "Order payment method (ex. Paypal, COD)", "type": "string", "example": "Paypal" }, "Note": { "description": "Note", "type": "string", "maxLength": 255, "example": "Ship by 25/06/2018" }, "Async": { "type": "boolean", "description": "Process the label generation async or sync. When false the label is\nreturned directly in the response; when true retrieve it later via\nGetLabelUrl or the Order Shipped webhook.\n", "example": false }, "CustomInfoContentsType": { "type": "string", "maxLength": 255, "description": "Type of goods declared to customs for cross-border shipments.", "enum": [ "documents", "gift", "merchandise", "returned_goods", "sample", "other" ], "example": "merchandise" }, "CarrierOptions": { "type": "array", "description": "Carrier-specific option name/value pairs.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "mydhlsaturday_delivery" }, "value": { "type": "string", "example": "1" } } } }, "CN22Info": { "type": "array", "description": "Customs (CN22) line items for cross-border shipments.", "items": { "type": "object", "properties": { "Description": { "description": "Optional CN22 item description (eg. \"Merchandise\")", "type": "string", "example": "test" }, "Weight": { "type": "number", "example": 2 }, "Quantity": { "description": "Optional CN22 item quantity (5)", "type": "integer", "example": 5 }, "UnitValue": { "description": "Optional CN22 item unit price (10.50)", "type": "number", "example": 10 }, "OriginCountry": { "description": "Optional CN22 origin country code (\"IT\")", "type": "string", "example": "IT" }, "Currency": { "description": "Optional CN22 price currency code (\"USD\")", "type": "string", "example": "USD" }, "HSCode": { "description": "Optional CN22 HSCode (\"123456\")", "type": "string", "example": "123456" }, "EAN": { "description": "Optional CN22 EAN (\"123456\")", "type": "string", "example": "123456" }, "VOC": { "type": "string", "description": "Volatile Organic Compound in grams.", "example": "12" } } } }, "ShipmentAmountPaid": { "type": "number", "description": "Amount paid by the customer for the shipment." }, "ShipmentCost": { "type": "number", "description": "Selected rate value." }, "ShipmentCostCurrency": { "type": "string", "description": "Selected rate currency." }, "CarrierNote": { "type": "string", "maxLength": 255, "description": "Carrier note (not supported by every carrier)." }, "UserNote": { "type": "string", "maxLength": 255, "description": "User note." }, "IsReturn": { "type": "boolean", "description": "Set true to create a Return Label." }, "IsDynamicMultiparcel": { "type": "boolean", "description": "Set `true` to add this parcel to a **progressive (dynamic) multiparcel**\nshipment โ€” one Ship call per parcel, for shipments whose parcel count is not\nknown when the first parcel ships. ShippyPro automatically groups the flagged\nshipments that share sender address, receiver address,\ncarrier connection and account into a single shipment, and every call returns\nits own label. Parcels sent from two different sender addresses stay in two\nseparate shipments. The shipment is confirmed to the carrier only at closeout, with\n`CloseShipments`. Availability depends on the carrier and on your contract โ€”\nask your ShippyPro account manager. Without the flag the shipment ships as\nordinary static multiparcel. See the *Progressive Multiparcel* section of the\nShip method for the full flow.\n" }, "non_delivery_option": { "type": "string", "description": "Only for dutiable shipments. `return` = send back to the sender,\n`abandon` = parcel abandoned by the consignee.\n", "enum": [ "return", "abandon" ] }, "zone_name": { "type": "string", "description": "Pricing zone name. Required only if `detailed_pricing` is set." }, "weight_range": { "type": "string", "description": "Pricing weight range. Required only if `detailed_pricing` is set." }, "detailed_pricing": { "type": "array", "description": "Pricing information (minimum 1 item).", "items": { "type": "object", "required": [ "type", "price", "desc" ], "properties": { "type": { "type": "string", "description": "Pricing type.", "enum": [ "tariff", "additional_parcels_surcharge", "carrier_option", "cod_surcharge", "exceed_dimension_l", "exceed_dimension_w", "exceed_dimension_h", "exceed_dimension", "exceed_parcel_surcharge", "fixed_surcharge", "fuel_surcharge", "insurance_surcharge", "triangle_surcharge", "vat_surcharge" ] }, "price": { "description": "Price (inside each detailed_pricing item)", "type": "number", "example": 7.6 }, "desc": { "description": "Pricing description (inside each detailed_pricing item)", "type": "string", "example": "Base tariff" } } } }, "LabelType": { "type": "string", "description": "Label type (\"PDF\" or \"ZPL\"); conversion happens automatically." }, "LabelWidth": { "type": "number", "description": "Label width in cm (for PDF)." }, "LabelHeight": { "type": "number", "description": "Label height in cm (for PDF)." }, "Rotate": { "type": "integer", "description": "Label rotation in degrees (only when a format conversion is applied)." }, "PageNumber": { "type": "integer", "description": "Index of the label to retrieve." }, "SplitPages": { "type": "boolean", "description": "Set true to split the labels." }, "PostShipmentETD": { "type": "boolean", "description": "Set true to send shipment documents later via the UploadPaperlessPostShip method." }, "ReturnCarrierName": { "type": "string", "description": "Return Label Combination โ€” carrier name for the return leg. Return\ntracking lasts 30 days after label creation by default; an extension\nup to 120 days is possible.\n", "example": "Generic" }, "ReturnCarrierService": { "type": "string", "description": "Return Label Combination โ€” carrier service for the return leg.", "example": "Standard" }, "ReturnCarrierID": { "type": "integer", "description": "Return Label Combination โ€” carrier ID for the return leg.", "example": 6 }, "ReturnInsurance": { "type": "number", "description": "Insurance value for the return leg (default 0).", "example": 10 }, "ReturnInsuranceCurrency": { "type": "string", "description": "Insurance currency for the return leg. Required if ReturnInsurance is set.", "example": "EUR" }, "ReturnCarrierOptions": { "type": "array", "description": "Carrier options for the return leg.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "upsdangerousgoods" }, "value": { "type": "string", "example": "1" } } } }, "return_to": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "Return Address Override โ€” used with Return Label Combination to send\nreturns to a different address (e.g. a dedicated warehouse).\n" }, "Attributes": { "type": "object", "description": "Free-form order attributes (custom name/value pairs), usable for\nmarking or retrieving shipments and printable on labels via Label\nDesign. Some attributes are managed by the platform: `sp_ioss`\nbinds an IOSS number that is used instead of the default one from\nthe Profile section and transmitted to the carriers.\n", "additionalProperties": true, "example": { "sp_ioss": "IOSS123456" } } } }, "ShipResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "NewOrderID": { "type": "string", "example": "1234567" }, "LabelURL": { "description": "Label URL(s). An empty array (`[]`) when the order is in error, a\nsingle string when there is one label, or an array of strings when\nthere is more than one.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "https://cdn.shippypro.com/labels/first_label.zpl", "https://cdn.shippypro.com/labels/second_label.zpl" ] }, "PDF": { "type": "array", "description": "List of PDF labels.", "items": { "type": "string" } }, "ZPL": { "type": "array", "description": "List of ZPL labels.", "items": { "type": "string" } }, "TrackingCarrier": { "type": "string", "example": "SpringXBS" }, "TrackingNumber": { "type": "string", "example": "UD26123123456" }, "TrackingExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have (e.g. multiparcel).", "items": { "type": "object", "additionalProperties": true } }, "DeliveryCarrier": { "type": [ "string", "null" ], "description": "Delivery carrier when available and different from the tracking carrier; otherwise null.", "example": "PostNL Packet Tracked" }, "Status": { "type": "string", "description": "`1` if the label was generated correctly, `2` if an error occurred.", "example": "1" }, "ErrorMessage": { "type": "string", "description": "Error message if an error occurred.", "example": "Error123" }, "ReturnErrorMessage": { "type": "string", "description": "Carrier error message if an error occurred on the return order.", "example": "Error123" }, "ErrorType": { "$ref": "#/components/schemas/ErrorType" }, "ReturnErrorType": { "$ref": "#/components/schemas/ErrorType" }, "ErrorSuggestion": { "$ref": "#/components/schemas/ErrorSuggestion" }, "ReturnErrorSuggestion": { "$ref": "#/components/schemas/ErrorSuggestion" }, "Parcels": { "type": [ "array", "null" ], "description": "Per-parcel breakdown of outbound trackings + labels. `null` when no\nparcel has both a tracking number and a label (e.g. the carrier\nreturned only customs forms). For Return Label In The Box (RLITB)\nshipments the return labels are emitted as items of this same array\nwith no marker distinguishing outbound from return parcels; clients\nmust rely on out-of-band knowledge (e.g. the order configuration)\nor carrier-specific conventions to tell them apart.\n", "items": { "$ref": "#/components/schemas/ShipParcel" } }, "ReturnParcels": { "type": [ "array", "null" ], "description": "Per-parcel breakdown of return trackings + labels. Present only when\nthe request used a Return Label Combination (ReturnCarrierName /\nReturnCarrierID / ReturnCarrierService); absent for outbound-only\nshipments and for Return Label In The Box. `Attributes` is mirrored\npositionally from `Parcels[i].Attributes` โ€” return parcel attributes\nare not stored independently; if there is no outbound parcel at the\nsame index, `Attributes` is an empty object.\n", "items": { "$ref": "#/components/schemas/ShipParcel" } } } }, "ErrorType": { "type": "object", "description": "Type of error when an operation was not successful.", "properties": { "code": { "type": "string", "description": "Error type unique identifier.", "example": "ADDRESS_INVALID" }, "name": { "type": "string", "description": "Unique name of the error type.", "example": "Invalid address" }, "typeDescription": { "type": "string", "description": "Description of the error type.", "example": "The recipient address was rejected by the carrier." } } }, "ErrorSuggestion": { "type": "object", "description": "Description and potential solution for an occurred error.", "properties": { "errorDescription": { "type": "string", "description": "Description of the error.", "example": "The recipient street exceeds the maximum length accepted by the carrier." }, "solution": { "type": "string", "description": "Proposed solution to the occurred error.", "example": "Shorten the street field and generate the label again." }, "links": { "type": "array", "description": "URLs pointing at the relevant Help Center article.", "items": { "type": "string" }, "example": [ "https://help.shippypro.com/en/knowledge/api" ] } } }, "ShipParcel": { "type": "object", "description": "Per-parcel tracking + label detail.", "properties": { "TrackingNumber": { "type": "string", "example": "UD26123123456" }, "PDF": { "type": [ "string", "null" ], "description": "Base64-encoded PDF of this parcel's label. `null` if the carrier returned none." }, "ZPL": { "type": [ "string", "null" ], "description": "Raw ZPL label string for this parcel. `null` if the carrier returned none." }, "Attributes": { "type": "object", "description": "Free-form per-parcel attributes. Empty object if none.", "additionalProperties": true } } }, "GetTrackingParams": { "type": "object", "required": [ "Code" ], "properties": { "Code": { "type": "string", "description": "Tracking number.", "example": "1ZA103756899507566" } } }, "GetTrackingResponse": { "type": "object", "properties": { "Carrier": { "type": "string", "example": "UPS" }, "CarrierLogo": { "type": "string", "example": "https://www.shippypro.com/sites/all/themes/shippypro_theme/assets_pannello/images/corrieri/Logo_UPS.png" }, "Completed": { "type": "boolean", "example": true }, "EstimatedDeliveryDate": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1489659960" }, "StatusCode": { "type": "number", "description": "ShippyPro tracking status code:\n`1` Info Received, `2` In Transit, `3` Out for Delivery,\n`4` Missed Delivery, `5` Exception, `6` Delivered.\n", "enum": [ 1, 2, 3, 4, 5, 6 ], "example": 6 }, "ExtendedStatusCode": { "type": "number", "description": "Extended (granular) tracking status code. See the extended status\ntable: 1000 Info Received; 2000 In transit; 2100 Dropped by customer;\n2200 Collected by carrier; 2300 Carrier handling; 2310 Arrived at\nterminal/hub; 2320 Processing at terminal/hub; 2330 Departed from\nterminal/hub; 2400 Customs Clearance; 2500 Delivery planned;\n3000 Out for Delivery; 3100 Delivery in progress; 3200 Available for\npickup at PUDO/Facility; 4000 Failed Attempt; 5000 Generic Exception;\n5100 Transit Disruptions; 5110 Delayed; 5120 External causes;\n5200 Operational Issues; 5210 Misrouted; 5220 Pickup not possible;\n5230 On Hold; 5300 Parcel Exception; 5310 Exceeded dimensions or\nweight; 5320 Damaged; 5330 Lost; 5340 Destroyed; 5400 Address\nDiscrepancies; 5410 Insufficient address information; 5420 Wrong\naddress information; 5500 Customs and Documentation; 5510\nCustoms-related issues; 5520 Missing documents; 5600\nSender/Recipient-Related Events; 5610 Recipient exception; 5620\nSender exception; 5630 Returning to sender; 5640 Returned to\nsender; 5700 Carrier Actions; 5710 Carrier asks to be contacted;\n5720 Change to delivery; 5730 Other Carrier Exception; 6000\nDelivered; 6900 Manually Marked as Delivered; 9999 Not mapped.\n", "enum": [ 1000, 2000, 2100, 2200, 2300, 2310, 2320, 2330, 2400, 2500, 3000, 3100, 3200, 4000, 5000, 5100, 5110, 5120, 5200, 5210, 5220, 5230, 5300, 5310, 5320, 5330, 5340, 5400, 5410, 5420, 5500, 5510, 5520, 5600, 5610, 5620, 5630, 5640, 5700, 5710, 5720, 5730, 6000, 6900, 9999 ], "example": 6000 }, "FirstStatusDate": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1489419660" }, "Late": { "type": "boolean", "example": false }, "ExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have.", "items": { "type": "object", "additionalProperties": true } }, "Details": { "type": "array", "description": "Tracking status events, ordered by date, most recent first.", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1489659960" }, "message": { "type": "string", "example": "DELIVERED" }, "city": { "type": "string", "example": "MOTRIL" }, "StatusCode": { "type": "number", "example": 6 } } } } } }, "PingParams": { "type": "object", "description": "No parameters.", "additionalProperties": false }, "PingResponse": { "type": "object", "properties": { "Result": { "type": "boolean", "example": true } } }, "EditParams": { "type": "object", "required": [ "to_address", "from_address", "parcels", "OrderID", "ContentDescription", "Insurance", "InsuranceCurrency", "CashOnDelivery", "CashOnDeliveryCurrency", "CashOnDeliveryType" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels included in the shipment (minimum 1).", "items": { "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "description": "Parcel Length", "type": "number", "example": 5 }, "width": { "description": "Parcel width", "type": "number", "example": 5 }, "height": { "description": "Parcel height", "type": "number", "example": 5 }, "weight": { "description": "Parcel weight", "type": "number", "example": 10 }, "dimension_unit": { "type": "string", "description": "Unit of measurement for dimensions: \"CM\" (default) or \"IN\".", "example": "CM" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight: \"KG\" (default), \"LB\", \"OZ\".", "example": "KG" } } } }, "OrderID": { "type": "string", "description": "The order number obtained from a previous Ship API call.", "example": "8587891" }, "TotalValue": { "type": "string", "description": "Declared value with currency, e.g. `\"123 EUR\"`. Required for international shipments. The only accepted punctuation is `.` before the decimal digits; any other punctuation causes an error.", "example": "123 EUR" }, "ContentDescription": { "description": "Description of the content", "type": "string", "maxLength": 255, "example": "Milk" }, "Insurance": { "description": "Insurance value (default: 0)", "type": "number", "example": 0 }, "InsuranceCurrency": { "description": "Insurance currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "CashOnDelivery": { "description": "Cash on delivery value (default: 0)", "type": "number", "example": 0 }, "CashOnDeliveryCurrency": { "description": "Cash on delivery currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "CashOnDeliveryType": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "0 = Cash (default), 1 = Cashier's check, 2 = Check, 3 = All Payment Methods.", "example": 0 }, "ShipmentAmountPaid": { "type": "number", "description": "Amount paid by the customer for the shipment." }, "ShipmentCost": { "type": "number", "description": "Selected rate value." }, "ShipmentCostCurrency": { "type": "string", "description": "Selected rate currency." }, "Incoterm": { "type": "string", "enum": [ "DAP", "DDP", "EXW" ], "description": "Shipment incoterm: DAP, DDP or EXW (default DAP for cross-border).", "example": "DAP" }, "BillAccountNumber": { "description": "Bill the shipment to third party account number (default: '')", "type": "string", "example": "" }, "Note": { "description": "Note", "type": "string", "maxLength": 255, "example": "Ship by 25/06/2018" }, "CarrierNote": { "type": "string", "maxLength": 255, "description": "Carrier note (not supported by every carrier)." }, "IsReturn": { "type": "boolean", "description": "Set true to create a Return Label." }, "Async": { "type": "boolean", "description": "Process the request async (get the label directly in the response).", "example": false }, "LabelType": { "type": "string", "description": "Label type (\"PDF\" or \"ZPL\"); conversion happens automatically." }, "LabelWidth": { "type": "number", "description": "Label width in cm (for PDF)." }, "LabelHeight": { "type": "number", "description": "Label height in cm (for PDF)." }, "Rotate": { "type": "integer", "description": "Label rotation in degrees (only when a conversion is needed)." }, "PageNumber": { "type": "integer", "description": "Index of the label to retrieve." }, "SplitPages": { "type": "boolean", "description": "Set true to split the labels." } } }, "EditResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "LabelURL": { "type": "string", "example": "https://cdn.shippypro.com/labels/label.pdf" }, "PDF": { "type": "array", "description": "List of PDF labels.", "items": { "type": "string" } }, "ZPL": { "type": "array", "description": "List of ZPL labels.", "items": { "type": "string" } }, "TrackingCarrier": { "type": "string", "example": "Generic" }, "TrackingNumber": { "type": "string", "example": "UD26123123456" }, "TrackingExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have (e.g. multiparcel).", "items": { "type": "object", "additionalProperties": true } }, "Status": { "type": "string", "description": "Order status.", "example": "1" }, "ErrorMessage": { "type": "string", "description": "Error message if an error occurred.", "example": "Error123" }, "ErrorType": { "$ref": "#/components/schemas/ErrorType" }, "ErrorSuggestion": { "$ref": "#/components/schemas/ErrorSuggestion" } } }, "EditPartialParams": { "type": "object", "required": [ "OrderID", "PartialEdit" ], "properties": { "OrderID": { "type": "string", "description": "The order number obtained from a previous Ship API call.", "example": "8587891" }, "PartialEdit": { "type": "boolean", "description": "Required to perform a partial edit.", "example": true }, "Attributes": { "type": "array", "description": "Optional parcel attributes as custom name/value pairs.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "parcelID" }, "value": { "type": "string", "example": "123456" } } } }, "Note": { "type": "string", "maxLength": 255, "description": "Note.", "example": "Ship by 25/06/2018" }, "UserNote": { "type": "string", "maxLength": 255, "description": "User note.", "example": "Internal ref. 998877" } } }, "EditPartialResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "GetRatesParams": { "type": "object", "required": [ "to_address", "from_address", "parcels", "ContentDescription", "ShippingService" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels information (minimum 1).", "items": { "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "description": "Parcel Length", "type": "number", "example": 5 }, "width": { "description": "Parcel width", "type": "number", "example": 5 }, "height": { "description": "Parcel height", "type": "number", "example": 5 }, "weight": { "description": "Parcel weight", "type": "number", "example": 10 }, "dimension_unit": { "type": "string", "description": "Unit of measurement for dimensions: \"CM\" (default) or \"IN\".", "example": "CM" }, "weight_unit": { "type": "string", "description": "Unit of measurement for weight: \"KG\" (default), \"LB\", \"OZ\".", "example": "KG" }, "package": { "type": "integer", "description": "Carrier predefined package type (FedEx only for GetRates); use\nthe `value` attribute obtained through the\nGetCarrierPackagesTypes method.\n", "example": 1 } } } }, "Insurance": { "description": "Insurance value (default: 0)", "type": "number", "example": 0 }, "InsuranceCurrency": { "description": "Insurance currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "CashOnDelivery": { "description": "Cash on delivery value (default: 0)", "type": "number", "example": 0 }, "CashOnDeliveryCurrency": { "description": "Cash on delivery currency (default: \"EUR\"), see here", "type": "string", "maxLength": 3, "example": "EUR" }, "ContentDescription": { "description": "Description of the content", "type": "string", "maxLength": 255, "example": "Shoes" }, "TotalValue": { "type": "string", "description": "Declared value with currency, e.g. `\"120.50 EUR\"`. Required for international shipments. The only accepted punctuation is `.` before the decimal digits; any other punctuation causes an error.", "example": "50.25 EUR" }, "ShippingService": { "type": "string", "description": "Customer-selected shipping service (e.g. Express, Standard).", "example": "Standard" }, "RateCarriers": { "type": "array", "description": "Rate only specific carriers, e.g. `[\"CarrierName|CarrierID\", โ€ฆ]`.", "items": { "type": "string" } }, "IsReturn": { "type": "boolean", "description": "Set true if the order is a return." }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number. Required to apply the\nShippingService shipping rule: if TransactionID is not populated โ€”\nor does not match an order to ship โ€” the ShippingService filter is\nskipped.\n" }, "CarrierOptions": { "type": "array", "description": "Carrier-specific option name/value pairs to apply when rating.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "upsdangerousgoods" }, "value": { "type": "string", "example": "1" } } } } } }, "GetRatesResponse": { "type": "object", "properties": { "Rates": { "type": "array", "description": "List of available carrier rates.", "items": { "type": "object", "description": "Single carrier rate.", "properties": { "carrier": { "type": "string", "example": "Generic" }, "carrier_id": { "type": "string", "example": "6" }, "carrier_label": { "type": "string", "example": "Generic Test" }, "rate": { "type": "string", "example": "7.60" }, "rate_id": { "type": "string", "example": "orderRate" }, "order_id": { "type": "string", "example": "orderID" }, "delivery_days": { "type": [ "number", "string" ], "description": "Estimated delivery days. May be a number (e.g. 2) or a string (e.g. \"2-5\").", "example": 2 }, "service": { "type": "string", "example": "Standard" }, "zone_name": { "type": "string", "example": "Italy" }, "weight_range": { "type": "string", "example": "0-500" }, "detailed_pricing": { "type": "object", "description": "List of pricing items.", "properties": { "type": { "type": "string", "example": "tariff" }, "price": { "type": "number", "example": 7.6 }, "desc": { "type": "string", "example": "Tariff" } } } } } }, "RatesErrors": { "type": "array", "description": "List of per-carrier rate errors.", "items": { "type": "object", "description": "Single rate error.", "properties": { "carrier": { "type": "string", "example": "UPS" }, "carrier_id": { "type": "string", "example": "52" }, "carrier_label": { "type": "string", "example": "UPS Test" }, "error_message": { "type": "string", "example": "Service not available" }, "error_level": { "type": "number", "description": "0 = Error (carrier error), 1 = Warning (fixable ShippyPro-side error).", "example": 0 } } } } } }, "CheckAddressParams": { "type": "object", "required": [ "CarrierName", "CarrierID", "Address", "FromAddress" ], "properties": { "CarrierName": { "type": "string", "description": "Selected rate carrier name. Use `Generic` to skip carrier-side validation.", "example": "DHLExpress" }, "CarrierID": { "type": "integer", "description": "Selected rate carrier ID.", "example": 23 }, "Address": { "$ref": "#/components/schemas/Address" }, "FromAddress": { "$ref": "#/components/schemas/Address" }, "SkipValidationFields": { "type": "array", "description": "Address fields that will not be validated.", "items": { "type": "string" } } } }, "CheckAddressResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "`OK` on success.", "example": "OK" }, "Message": { "type": "array", "description": "Array or string of errors returned from validation.", "items": { "type": "string" } }, "Suggestions": { "type": "array", "description": "Address suggestions returned from the carrier API (not from geocoding).", "items": { "type": "object", "additionalProperties": true } }, "NewAddress": { "type": "object", "description": "The corrected address, composed by replacing incorrect fields with suggested values.", "properties": { "street1": { "type": "string" }, "street2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "administrativeAreaLevel1": { "type": "string", "description": "Only present if available. Represents a state or region depending on country." }, "administrativeAreaLevel2": { "type": "string", "description": "Only present if available. Represents a county, province or district depending on country." }, "administrativeAreaLevel3": { "type": "string", "description": "Only present if available. Generally represents a city." } } }, "Accuracy": { "type": "number", "description": "Level of accuracy of the match between the provided and returned address (95, 75, 60 or 40).", "example": 95 }, "Verified": { "type": "boolean", "description": "Only present when GeoCoding validation was performed. `true` when\nthe address was confirmed to an exact location; `false` when the\naddress was accepted but could not be verified to the exact location\n(in which case no address corrections are suggested).\n" }, "ValidationErrors": { "type": "string", "description": "Validation errors, if any." } } }, "IsResidentialAddressParams": { "type": "object", "required": [ "Address" ], "properties": { "Address": { "allOf": [ { "$ref": "#/components/schemas/Address" } ], "description": "The address to classify. `name` is required if `company` is empty,\nand `company` is required if `name` is empty (max 255 chars each).\n" } } }, "IsResidentialAddressResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "`OK` if the call succeeded, `NOK` otherwise.", "example": "OK" }, "IsResidentialAddress": { "type": "boolean", "description": "`true` if the address is residential (a home), `false` otherwise.", "example": true } } }, "BookPickupParams": { "type": "object", "required": [ "to_address", "from_address", "parcels", "CarrierName", "CarrierID", "PickupTime", "PickupMorningMintime", "PickupMorningMaxtime", "PickupAfternoonMintime", "PickupAfternoonMaxtime" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels to be picked up (minimum 1).", "items": { "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "description": "Parcel Length", "type": "number", "example": 5 }, "width": { "description": "Parcel width", "type": "number", "example": 5 }, "height": { "description": "Parcel height", "type": "number", "example": 5 }, "weight": { "type": "number", "description": "Parcel weight (default unit KG).", "example": 10 }, "dimension_unit": { "type": "string", "description": "Parcel dimension unit. Default `CM`. Accepted: `CM`, `IN`.", "example": "CM" }, "weight_unit": { "type": "string", "description": "Parcel weight unit. Default `KG`. Accepted: `KG`, `LB`, `OZ`, `G`.", "example": "KG" } } } }, "CarrierName": { "description": "Carrier name", "type": "string", "example": "DHLExpress" }, "CarrierID": { "description": "Carrier ID", "type": "integer", "example": 20 }, "PickupTime": { "type": "integer", "description": "Pickup time as a Unix timestamp (seconds).", "example": 1517564402 }, "PickupNote": { "description": "Pickup note", "type": "string", "maxLength": 255, "example": "Urgent" }, "PickupMorningMintime": { "type": "string", "maxLength": 5, "description": "Minimum pickup time - morning (24h format, e.g. 09:00).", "example": "09:00" }, "PickupMorningMaxtime": { "type": "string", "maxLength": 5, "description": "Maximum pickup time - morning (24h format, e.g. 13:00).", "example": "12:00" }, "PickupAfternoonMintime": { "type": "string", "maxLength": 5, "description": "Minimum pickup time - afternoon (24h format, e.g. 14:00).", "example": "14:00" }, "PickupAfternoonMaxtime": { "type": "string", "maxLength": 5, "description": "Maximum pickup time - afternoon (24h format, e.g. 18:00).", "example": "18:00" }, "orderIds": { "type": "string", "description": "Order IDs separated by a semicolon (e.g. `123;245`). Required for some carriers.", "example": "123;245" }, "emailSubject": { "type": "string", "description": "Main part of the email subject (default `Pickup Request`)." } } }, "BookPickupResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Message": { "type": "string", "example": "Booked" }, "ConfirmationID": { "type": "string", "example": "1598" } } }, "GetPickupsParams": { "type": "object", "description": "If neither field is set, all scheduled pickups are returned.", "properties": { "OrderID": { "type": "integer", "description": "ShippyPro Order ID.", "example": 123456 }, "ConfirmationID": { "type": "string", "description": "Confirmation ID (see the [BookPickup](#v1/tag/pickup/POST/v1/BookPickup) response)." } } }, "GetPickupsResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Pickups": { "type": "array", "description": "List of your scheduled pickups.", "items": { "type": "object", "properties": { "CarrierName": { "type": "string", "example": "POSTEITALIANE" }, "CarrierID": { "type": "string", "example": "1" }, "Date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1560423600" }, "PickupMorningMintime": { "type": "string", "example": "09:00" }, "PickupMorningMaxtime": { "type": "string", "example": "14:00" }, "PickupAfternoonMintime": { "type": "string", "example": "14:00" }, "PickupAfternoonMaxtime": { "type": "string", "example": "19:00" }, "Name": { "type": "string", "example": "mario rossi" }, "Company": { "type": "string", "example": "mario rossi" }, "Street1": { "type": "string", "example": "via firenze" }, "Street2": { "type": "string", "example": "civico 55" }, "City": { "type": "string", "example": "Milano" }, "Country": { "type": "string", "example": "IT" }, "State": { "type": "string", "example": "MI" }, "Postcode": { "type": "string", "example": "20081" }, "Phone": { "type": "string", "example": "123456" }, "Email": { "type": "string", "example": "test@gmail.com" }, "Note": { "type": "string", "example": "your note" }, "ConfirmationID": { "type": "string", "example": "CP8360029" }, "PickedUP": { "type": "string", "example": "0" }, "OrderIDS": { "type": "array", "items": { "type": "string" }, "example": [ "1" ] }, "Parcels": { "type": "array", "description": "List of parcels.", "items": { "type": "object", "properties": { "weight": { "type": "number", "example": 0.03 }, "height": { "type": "number", "example": 51 }, "width": { "type": "number", "example": 51 }, "length": { "type": "number", "example": 51 } } } } } } } } }, "CancelPickupParams": { "type": "object", "required": [ "CarrierName", "CarrierID", "ConfirmationNumber", "PickupTime" ], "properties": { "CarrierName": { "description": "Pickup Carrier name", "type": "string", "example": "UPS" }, "CarrierID": { "description": "Pickup Carrier ID", "type": "integer", "example": 1 }, "ConfirmationNumber": { "type": "string", "description": "Pickup confirmation number.", "example": "1598" }, "PickupTime": { "type": "integer", "description": "Pickup time as a Unix timestamp (seconds).", "example": 1517564402 } } }, "CancelPickupResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "GetPickupAvailabilityParams": { "type": "object", "required": [ "to_address", "from_address", "PickupTime", "PickupMorningMintime", "PickupMorningMaxtime", "PickupAfternoonMintime", "PickupAfternoonMaxtime" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels information (minimum 1).", "items": { "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "description": "Parcel Length", "type": "number", "example": 5 }, "width": { "description": "Parcel width", "type": "number", "example": 5 }, "height": { "description": "Parcel height", "type": "number", "example": 5 }, "weight": { "type": "number", "description": "Parcel weight (default unit KG).", "example": 10 }, "dimension_unit": { "type": "string", "description": "Parcel dimension unit. Default `CM`. Accepted: `CM`, `IN`.", "example": "CM" }, "weight_unit": { "type": "string", "description": "Parcel weight unit. Default `KG`. Accepted: `KG`, `LB`, `OZ`, `G`.", "example": "KG" } } } }, "PickupCarriers": { "type": "array", "description": "Retrieve availability only for specific carriers, e.g. `[\"CarrierName|CarrierID\", โ€ฆ]`.", "items": { "type": "string" }, "example": [ "FEDEX|6" ] }, "PickupTime": { "type": "integer", "description": "Pickup time as a Unix timestamp (seconds).", "example": 1517564402 }, "PickupMorningMintime": { "type": "string", "maxLength": 5, "description": "Minimum pickup time - morning (24h format, e.g. 09:00).", "example": "09:00" }, "PickupMorningMaxtime": { "type": "string", "maxLength": 5, "description": "Maximum pickup time - morning (24h format, e.g. 13:00).", "example": "12:00" }, "PickupAfternoonMintime": { "type": "string", "maxLength": 5, "description": "Minimum pickup time - afternoon (24h format, e.g. 14:00).", "example": "14:00" }, "PickupAfternoonMaxtime": { "type": "string", "maxLength": 5, "description": "Maximum pickup time - afternoon (24h format, e.g. 18:00).", "example": "18:00" }, "MaxBusinessDays": { "type": "integer", "description": "Maximum number of business days to consider when checking. Default 1.", "example": 1 } } }, "GetPickupAvailabilityResponse": { "type": "object", "properties": { "Availabilities": { "type": "array", "description": "List of pickup availabilities.", "items": { "type": "object", "description": "Single carrier pickup availability.", "properties": { "Carrier": { "type": "string", "example": "FEDEX" }, "CarrierID": { "type": "string", "example": "6" }, "CarrierLabel": { "type": "string", "example": "FEDEX Test 1" }, "Service": { "type": "string", "example": "INTERNATIONAL_ECONOMY" }, "ServiceType": { "type": "string", "example": "INTERNATIONAL" }, "PickupDate": { "type": "string", "example": "2023-05-15" }, "MinPickupReadyTime": { "type": "string", "example": "09:00" }, "MaxPickupReadyTime": { "type": "string", "example": "18:00" }, "PickupAccessTime": { "type": "string", "description": "Minimum time window the courier needs between the shipment's\nready time and the cut-off/close time to complete the pickup.\nA duration (e.g. `PT1H30M`), not a clock time. Can be an empty\nstring when the carrier does not return it (e.g. MyDHL).\n", "example": "PT1H0M" } } } }, "AvailabilitiesErrors": { "type": "array", "description": "List of per-carrier errors.", "items": { "type": "object", "description": "Single pickup availability error.", "properties": { "Carrier": { "type": "string", "example": "FEDEX" }, "CarrierID": { "type": "string", "example": "52" }, "CarrierLabel": { "type": "string", "example": "FEDEX Test 2" }, "ErrorMessage": { "type": "string", "example": "Service not available" } } } } } }, "GetMarketplacesParams": { "type": "object", "description": "All fields are optional; send an empty object to list every marketplace.", "properties": { "Active": { "type": "integer", "description": "Search for active (`1`) or non-active (`0`) marketplaces.", "example": 1 } } }, "GetMarketplacesResponse": { "type": "object", "properties": { "Marketplaces": { "type": "object", "description": "List of marketplaces. The key is the marketplace name.", "additionalProperties": { "type": "array", "description": "List of connections for that marketplace.", "items": { "type": "object", "properties": { "MarketplaceID": { "type": "string", "example": "15" }, "Label": { "type": "string", "example": "Amazon" } } } } } } }, "GetCarriersParams": { "type": "object", "description": "All fields are optional; send an empty object to list every carrier.", "properties": { "Active": { "type": "integer", "description": "Search for active (`1`) or non-active (`0`) carriers.", "example": 1 }, "Credentials": { "type": "object", "description": "Carrier credentials to retrieve, keyed by carrier name.", "additionalProperties": { "type": "array", "description": "Credential field names to retrieve for that carrier.", "items": { "type": "string" } } } } }, "GetCarriersResponse": { "type": "object", "properties": { "Carriers": { "type": "object", "description": "List of carriers. The key is the carrier name.", "additionalProperties": { "type": "array", "description": "List of connections for that carrier.", "items": { "type": "object", "properties": { "CarrierID": { "type": "string", "example": "10" }, "CarrierService": { "type": "string", "example": "NextDayAir" }, "ServicesList": { "type": "array", "description": "Carrier services.", "items": { "type": "string" }, "example": [ "NextDayAir", "2ndDayAir", "Ground" ] }, "Label": { "type": "string", "example": "UPS" } } } } } } }, "GetCarrierOptionsParams": { "type": "object", "required": [ "CarrierName", "CarrierID" ], "properties": { "CarrierName": { "description": "Carrier Name", "type": "string", "example": "SDA" }, "CarrierID": { "description": "Carrier ID", "type": "integer", "example": 34 }, "to_address": { "description": "Optional recipient address. Add it to also receive the carrier's\nPick-Up & Drop-Off point options.\n", "$ref": "#/components/schemas/Address" } } }, "GetCarrierOptionsResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Options": { "type": "object", "description": "List of carrier options. The key is the carrier option name.", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "example": "Floor Delivery" }, "parameters": { "type": "object", "description": "Option parameters to pass when using this option.", "additionalProperties": { "type": "string" }, "example": { "sdafloordelivery": "1" } }, "price": { "type": "string", "example": "1.10" } } } } } }, "GetCarrierPackagesTypesParams": { "type": "object", "description": "No parameters.", "additionalProperties": false }, "GetCarrierPackagesTypesResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "PackagesTypes": { "type": "object", "description": "List of carrier package types. The key is the carrier name.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "UPS Envelope" }, "attributes": { "type": "object", "properties": { "package-width": { "type": "number", "example": 30 }, "package-height": { "type": "number", "example": 1 }, "package-length": { "type": "number", "example": 24 } } }, "value": { "type": "number", "example": 1 } } } } } } }, "CreateManifestParams": { "type": "object", "required": [ "OrderIDS" ], "properties": { "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs.", "items": { "type": "integer" }, "example": [ 1234 ] } } }, "CreateManifestResponse": { "type": "object", "properties": { "ManifestNumber": { "type": "string", "example": "23" }, "ManifestURL": { "description": "Manifest URL. A string when a single manifest was generated, or an\narray of strings when more than one was generated.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "https://cdn.shippypro.com/manifests/manifest-u11n23-15332055452.pdf" } } }, "GetManifestParams": { "type": "object", "required": [ "ManifestNumber" ], "properties": { "ManifestNumber": { "type": "string", "description": "Manifest number.", "example": "10" } } }, "GetManifestResponse": { "type": "object", "properties": { "ManifestNumber": { "type": "string", "example": "23" }, "ManifestURL": { "description": "Manifest URL. A string when a single manifest was generated, or an\narray of strings when more than one was generated.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "https://cdn.shippypro.com/manifests/manifest-u11n23-15332055452.pdf" }, "OrderIDS": { "type": "array", "description": "List of ShippyPro orders.", "items": { "type": "string" }, "example": [ "1234" ] } } }, "DeleteManifestParams": { "type": "object", "required": [ "ManifestNumber" ], "properties": { "ManifestNumber": { "type": "string", "description": "Manifest number.", "example": "10" } } }, "DeleteManifestResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "CloseShipmentsParams": { "type": "object", "required": [ "CarrierName" ], "properties": { "CarrierName": { "description": "Carrier whose shipments are being closed โ€” the same value used in `Ship`,\navailable on the API Keys page and from `GetCarriers`. One call covers every\nconnection you hold to that carrier; there is no parameter for selecting one\nconnection.\n", "type": "string", "example": "Spring" }, "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs to close. If omitted, the call takes every order for this\ncarrier that has not been closed yet, going back one month.\n\nFor a progressive multiparcel shipment, naming one parcel closes **its whole\ngroup**: the IDs select which groups the call touches, not which parcels\nwithin them. Void the parcels you do not want to send before calling this\nmethod. Parcels transmitted in an earlier closeout are skipped rather than\nsent again.\n", "items": { "type": "integer" }, "example": [ 1234 ] } } }, "CloseShipmentsResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "Outcome of the closeout. Inspect it together with `ErrorMessage` โ€” the call returns `200` either way.", "example": "OK" }, "ErrorMessage": { "type": "string", "description": "Reason the closeout did not succeed; empty string when it did.", "example": "" }, "ManifestNumber": { "type": "number", "description": "Manifest number assigned by the carrier, when one was generated at closeout.", "example": 1 }, "ManifestURL": { "type": "array", "description": "List of manifest URLs; empty array if no manifests were generated.", "items": { "type": "string" }, "example": [ "https://cdn.shippypro.com/manifests/manifest-u11n1-15332055452.pdf" ] }, "AdditionalDocs": { "type": "array", "description": "List of base64-encoded files.", "items": { "type": "object", "properties": { "extension": { "type": "string", "example": "pdf" }, "base64": { "type": "string", "example": "base64..." } } } } } }, "UploadPaperlessDocumentationParams": { "type": "object", "required": [ "TransactionID", "Name", "Country", "Document" ], "properties": { "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number (max 255 chars).", "example": "19269" }, "Name": { "type": "string", "description": "Recipient name.", "example": "Mark" }, "Country": { "type": "string", "maxLength": 2, "description": "Recipient country ISO 3166-1 alpha-2 code (2 chars).", "example": "US" }, "Document": { "type": "string", "description": "PDF document, base64 encoded.", "example": "..." }, "DocumentType": { "type": "integer", "description": "Document type. One of: `0` Invoice (default), `1` Air Waybill,\n`2` Proforma invoice, `3` Certificate of Origin, `4` Usmca\nCertificate of Origin, `5` Commercial invoice, `6` Customs\ndeclaration, `99` Other.\n", "example": 0 } } }, "UploadPaperlessDocumentationResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "UploadPaperlessPostShipParams": { "type": "object", "required": [ "OrderID", "Documents" ], "properties": { "OrderID": { "type": "string", "description": "ShippyPro reference order number.", "example": "123456789" }, "Documents": { "type": "array", "description": "One object per uploaded document.", "items": { "type": "object", "required": [ "Document" ], "properties": { "Document": { "type": "string", "description": "PDF document, base64 encoded.", "example": "pdf_base64_encoded" }, "DocumentType": { "type": "integer", "description": "Document type. One of: `0` Invoice (default), `1` Air Waybill,\n`2` Proforma invoice, `3` Certificate of Origin, `4` Usmca\nCertificate of Origin, `5` Commercial invoice, `6` Customs\ndeclaration, `99` Other.\n", "example": 2 } } } } } }, "UploadPaperlessPostShipResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Message": { "type": "string", "example": "Documents uploaded successfully" } } }, "DeletePaperlessDocumentationParams": { "type": "object", "description": "Provide at least one of `TransactionID` or `Name`.", "properties": { "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number used at upload. Required if Name is not provided.", "example": "ORDER2365" }, "Name": { "type": "string", "description": "Recipient name used at upload. Required if TransactionID is not provided.", "example": "Mark" }, "DocumentType": { "type": "integer", "description": "Document type to narrow the deletion (same values as\nUploadPaperlessDocumentation): `0` Invoice (default), `1` Air\nWaybill, `2` Proforma invoice, `3` Certificate of Origin, `4` Usmca\nCertificate of Origin, `5` Commercial invoice, `6` Customs\ndeclaration, `99` Other.\n", "example": 5 } } }, "DeletePaperlessDocumentationResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Deleted": { "type": "number", "description": "Number of documents deleted.", "example": 2 }, "Skipped": { "type": "number", "description": "Number of matching documents skipped because already used.", "example": 1 } } }, "CreateCrossBorderInvoiceParams": { "type": "object", "required": [ "Incoterm", "TypeOfExport", "OrderId", "InvoiceNumber", "DateOfExportation", "ShipperExporter", "Consignee", "Goods" ], "properties": { "Incoterm": { "type": "string", "description": "The incoterm for the transaction.", "example": "EXW" }, "TypeOfExport": { "type": "string", "description": "The type of export.", "example": "Gift" }, "Currency": { "type": "string", "maxLength": 3, "description": "The currency used in the invoice (3 characters)." }, "NumberOfParcels": { "type": "string", "description": "The number of parcels involved in the shipment." }, "OrderId": { "type": "string", "description": "The unique order ID.", "example": "123456" }, "OrderReference": { "type": "string", "description": "The reference number for the order." }, "TotalLineItems": { "type": "string", "description": "The total number of line items." }, "TotalWeight": { "type": "string", "description": "The total weight of the shipment." }, "TotalAmount": { "type": "number", "description": "The total amount of the invoice." }, "TotalGst": { "type": "number", "description": "The total GST for the invoice." }, "WeightUOM": { "type": "string", "description": "The unit of measure for weight. Default is \"KG\"." }, "InvoiceType": { "type": "string", "description": "The type of invoice." }, "UploadETD": { "type": "string", "description": "Upload the generated invoice directly to the carrier of the indicated OrderId." }, "DeclarationNotes": { "type": "string", "description": "Additional notes for the declaration." }, "AirwaybillNumber": { "type": "string", "description": "The airway bill number for the shipment.", "example": "123456" }, "CustomReference": { "type": "string", "description": "A custom reference for the invoice." }, "InvoiceNumber": { "type": "string", "description": "The unique invoice number.", "example": "123456" }, "CountryOfExportDestination": { "type": "string", "maxLength": 2, "description": "The country of export destination (2 characters, ISO 3166-1 alpha-2).", "example": "IT" }, "DateOfExportation": { "type": "string", "description": "The date of exportation (ISO 8601 date, YYYY-MM-DD).", "example": "2021-01-01" }, "SignatureDate": { "type": "string", "description": "The date of signature (ISO 8601 date, YYYY-MM-DD)." }, "ShipperExporter": { "type": "object", "description": "Details of the exporter.", "required": [ "Name", "Address", "Zipcode", "City", "Country", "Telephone" ], "properties": { "Name": { "type": "string", "description": "Name of the exporter.", "example": "Exporter Name" }, "Address": { "type": "string", "description": "Address of the exporter.", "example": "Exporter Address" }, "Company": { "type": "string", "description": "Company name of the exporter." }, "Zipcode": { "type": "string", "description": "Zip code of the exporter.", "example": "12345" }, "City": { "type": "string", "description": "City of the exporter.", "example": "Exporter City" }, "Country": { "type": "string", "description": "Country of the exporter (2 characters, ISO 3166-1 alpha-2).", "example": "Exporter Country" }, "Telephone": { "type": "string", "description": "Telephone number of the exporter.", "example": "123456789" }, "VatNumber": { "type": "string", "description": "VAT number of the exporter." }, "Eori": { "type": "string", "description": "EORI number of the exporter." }, "CustomReference": { "type": "string", "description": "Custom reference for the exporter." } } }, "Importer": { "type": "object", "description": "Details of the importer.", "required": [ "Name", "Address", "Zipcode", "City", "Country", "Telephone" ], "properties": { "Name": { "type": "string", "description": "Name of the importer." }, "Company": { "type": "string", "description": "Company name of the importer." }, "Address": { "type": "string", "description": "Address of the importer." }, "Zipcode": { "type": "string", "description": "Zip code of the importer." }, "City": { "type": "string", "description": "City of the importer." }, "Country": { "type": "string", "description": "Country of the importer (2 characters, ISO 3166-1 alpha-2)." }, "Telephone": { "type": "string", "description": "Telephone number of the importer." }, "VatNumber": { "type": "string", "description": "VAT number of the importer." }, "Eori": { "type": "string", "description": "EORI number of the importer." }, "CustomReference": { "type": "string", "description": "Custom reference for the importer." } } }, "Consignee": { "type": "object", "description": "Details of the consignee.", "required": [ "Name", "Address", "Zipcode", "City", "Country", "Telephone" ], "properties": { "Name": { "type": "string", "description": "Name of the consignee.", "example": "Consignee Name" }, "Company": { "type": "string", "description": "Company name of the consignee." }, "Address": { "type": "string", "description": "Address of the consignee.", "example": "Consignee Address" }, "Zipcode": { "type": "string", "description": "Zip code of the consignee.", "example": "12345" }, "City": { "type": "string", "description": "City of the consignee.", "example": "Consignee City" }, "Country": { "type": "string", "description": "Country of the consignee (2 characters, ISO 3166-1 alpha-2).", "example": "Consignee Country" }, "Telephone": { "type": "string", "description": "Telephone number of the consignee.", "example": "123456789" }, "VatNumber": { "type": "string", "description": "VAT number of the consignee." }, "Eori": { "type": "string", "description": "EORI number of the consignee." }, "CustomReference": { "type": "string", "description": "Custom reference for the consignee." } } }, "Goods": { "type": "array", "description": "List of goods being exported (minimum 1 item).", "items": { "type": "object", "required": [ "ParcelCount", "Description", "HsCode", "Quantity", "Weight", "UnitValue" ], "properties": { "ParcelCount": { "type": "integer", "description": "The parcel number.", "example": 1 }, "TypeOfPackaging": { "type": "integer", "description": "The type of packaging used." }, "Marks": { "type": "string", "description": "Marks or labels on the goods." }, "Description": { "type": "string", "description": "Description of the goods.", "example": "Goods Description" }, "HsCode": { "type": "string", "description": "Harmonized System code.", "example": "123456" }, "CountryOfOrigin": { "type": "string", "description": "The country of origin of the goods." }, "Quantity": { "type": "integer", "description": "The quantity of the goods.", "example": 1 }, "QuantityUOM": { "type": "string", "description": "Unit of measure for quantity. Default is \"pcs\"." }, "Weight": { "type": "number", "description": "The weight of the goods.", "example": 1 }, "UnitValue": { "type": "number", "description": "Value per unit of the goods.", "example": 1 }, "GstPaid": { "type": "number", "description": "GST paid on the goods.", "example": 0 }, "SubTotalValue": { "type": "number", "description": "Subtotal value of the goods.", "example": 1 } } } } } }, "CreateCrossBorderInvoiceResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "CrossborderInvoice": { "type": "string", "description": "Base64 encoded PDF file of the generated invoice." } } }, "GetOrderParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "integer", "description": "ShippyPro Order ID.", "example": 612648 } } }, "GetOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "OrderID": { "type": "string", "example": "612648" }, "TransactionID": { "type": "string", "example": "1234" }, "CarrierID": { "type": "string", "example": "3" }, "TrackingCarrier": { "type": "string", "example": "DHL" }, "TrackingNumber": { "type": "string", "example": "8599848451" }, "TrackingExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers and tracking URLs the shipment may have (e.g. multiparcel, carrier-specific handling).", "items": { "type": "object", "additionalProperties": true } }, "MarketplacePlatform": { "type": "string", "example": "Amazon" }, "Status": { "type": "string", "description": "Current tracking status.", "example": "1" }, "LabelURL": { "type": "array", "description": "List of label URLs.", "items": { "type": "string" }, "example": [ "https://cdn.shippypro.com/labels/label.pdf" ] }, "ErrorMessage": { "type": "string", "description": "Error message if an error occurred.", "example": "Error123" }, "ErrorType": { "$ref": "#/components/schemas/ErrorType" }, "ErrorSuggestion": { "$ref": "#/components/schemas/ErrorSuggestion" } } }, "ArchiveOrdersParams": { "type": "object", "required": [ "OrderIDS" ], "properties": { "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs.", "items": { "type": "integer" }, "example": [ 1234 ] } } }, "ArchiveOrdersResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "UpdateOrdersParams": { "type": "object", "required": [ "OrderIDS" ], "properties": { "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs.", "items": { "type": "integer" }, "example": [ 1234 ] } } }, "UpdateOrdersResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "PutOrderParams": { "type": "object", "required": [ "to_address", "parcels", "TransactionID", "Date", "Currency", "ItemsCount", "ContentDescription", "Total", "Status", "ShipmentAmountPaid", "APIOrdersID", "Incoterm", "BillAccountNumber", "PaymentMethod", "ShippingService", "Note" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels information (minimum 1).", "items": { "description": "Containing items information", "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "type": "number", "description": "Parcel length (cm).", "example": 5 }, "width": { "type": "number", "description": "Parcel width (cm).", "example": 5 }, "height": { "type": "number", "description": "Parcel height (cm).", "example": 5 }, "weight": { "type": "number", "description": "Parcel weight (kg, 2 decimals).", "example": 10 } } } }, "items": { "type": "array", "description": "Items information.", "items": { "description": "Containing items information", "type": "object", "required": [ "title", "imageurl", "quantity", "price", "sku" ], "properties": { "title": { "type": "string", "description": "Item title.", "example": "Milk" }, "imageurl": { "type": "string", "description": "URL for the item's image.", "example": "http://www.shippypro.com/milk.png" }, "quantity": { "type": "integer", "description": "Quantity of items (must be a positive number).", "example": 5 }, "price": { "type": "number", "description": "Price of items.", "example": 5.99 }, "sku": { "type": "string", "description": "SKU of items.", "example": "milk" }, "origin_country": { "type": "string", "description": "Country of origin for the items." }, "hs_code": { "type": "string", "description": "HS Code of the items." } } } }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number (max 255 chars). Dots and whitespaces are converted to underscores, slashes to dashes, and hashes and double quotes are removed.", "example": "ORDER2365" }, "Date": { "type": "integer", "description": "Order timestamp (10 digits, e.g. 1657275360).", "example": 1492528071 }, "Currency": { "type": "string", "maxLength": 3, "description": "Order currency (3 chars, e.g. EUR).", "example": "EUR" }, "ItemsCount": { "type": "integer", "description": "Items count.", "example": 1 }, "ContentDescription": { "type": "string", "description": "Description of the content.", "example": "Milk" }, "Total": { "type": "number", "description": "Order value.", "example": 23.5 }, "Status": { "type": "string", "description": "Order status.", "example": "Paid" }, "ShipmentAmountPaid": { "type": "number", "description": "Amount paid for the shipment.", "example": 23.5 }, "APIOrdersID": { "type": "integer", "description": "APIOrders Marketplace ID.", "example": 30 }, "DrupalCommerceID": { "type": "integer", "description": "Drupal Marketplace ID." }, "Incoterm": { "type": "string", "enum": [ "DAP", "DDP", "EXW" ], "description": "Shipment incoterm: DAP, DDP or EXW. For cross-border shipments the default is DAP when not specified.", "example": "DAP" }, "BillAccountNumber": { "type": "string", "description": "Bill the shipment to third-party account number (default: '').", "example": "" }, "PaymentMethod": { "type": "string", "description": "Order payment method (e.g. Paypal, COD).", "example": "PayPal" }, "ShippingService": { "type": "string", "description": "Customer-selected shipping service (e.g. Express, Standard).", "example": "Expedited" }, "Note": { "type": "string", "maxLength": 255, "description": "Additional notes (max 255 chars).", "example": "Ship by 25/06/2018" } } }, "PutOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "VoidShipmentsParams": { "type": "object", "required": [ "OrderIDS", "CarrierName" ], "properties": { "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs to void.", "items": { "type": "integer" }, "example": [ 1234 ] }, "CarrierName": { "type": "string", "description": "Carrier name.", "example": "SDA" } } }, "VoidShipmentsResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "GetLabelUrlParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "integer", "description": "ShippyPro Order ID.", "example": 1234 }, "LabelType": { "type": "string", "description": "Label type (`PDF` or `ZPL`). Requests a specific format; conversion happens automatically.", "example": "PDF" }, "LabelWidth": { "type": "number", "description": "Label width (cm, for `PDF`)." }, "LabelHeight": { "type": "number", "description": "Label height (cm, for `PDF`)." }, "Rotate": { "type": "integer", "description": "Label rotation (in degrees, only applicable when a conversion is needed)." }, "PageNumber": { "type": "integer", "description": "Index of the label you want to retrieve." }, "SplitPages": { "type": "boolean", "description": "Set `true` if you want to split the labels." } } }, "GetLabelUrlResponse": { "type": "object", "properties": { "LabelURL": { "description": "Label URL. An empty array (`[]`) when the order is in error, a\nsingle string when the order has one label, or an array of strings\nwhen it has more than one label.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "https://cdn.shippypro.com/labels/label.pdf" }, "PDF": { "type": "array", "description": "List of base64-encoded PDF labels.", "items": { "type": "string" } }, "ZPL": { "type": "array", "description": "List of ZPL labels.", "items": { "type": "string" } }, "TrackingCarrier": { "type": "string", "example": "UPS" }, "TrackingNumber": { "type": "string", "example": "123456" }, "TrackingExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "DeliveryCarrier": { "type": [ "string", "null" ], "description": "Delivery carrier when available and different from the tracking carrier; otherwise null.", "example": "PostNL Packet Tracked" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have (e.g. multiparcel).", "items": { "type": "object", "additionalProperties": true } }, "Status": { "type": "number", "example": 1 }, "Parcels": { "type": [ "array", "null" ], "description": "Per-parcel breakdown of outbound trackings + labels. `null` when no\nparcel has both a tracking number and a label.\n", "items": { "$ref": "#/components/schemas/ShipParcel" } }, "ReturnParcels": { "type": [ "array", "null" ], "description": "Per-parcel breakdown of return trackings + labels for orders created\nvia Return Label Combination. Absent for outbound-only shipments and\nfor Return Label In The Box (RLITB).\n", "items": { "$ref": "#/components/schemas/ShipParcel" } } } }, "GetPendingOrdersParams": { "type": "object", "properties": { "DateMin": { "type": "integer", "description": "Filter date from (Unix timestamp, seconds).", "example": 1657275360 }, "DateMax": { "type": "integer", "description": "Filter date to (Unix timestamp, seconds).", "example": 1657375360 }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number." }, "IncludeItemsAttributes": { "type": "boolean", "description": "If set, include item attributes (Shopify/Maxpho; Magento requires items mapping)." }, "ExcludeReturns": { "type": "boolean", "description": "If set, exclude returns." } } }, "GetPendingOrdersResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Total": { "type": "number", "example": 1 }, "Orders": { "type": "array", "description": "List of pending orders.", "items": { "type": "object", "description": "Order object.", "properties": { "transaction_id": { "type": "string", "example": "030-9029737-3012345" }, "date": { "type": "string", "example": "1563444659" }, "currency": { "type": "string", "example": "GBP" }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Acqua Colonia spray, 180ml." }, "quantity": { "type": "string", "example": "1" }, "price": { "type": "string", "example": "45.27" }, "sku": { "type": "string", "example": "2777228_-1862500000" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute_name": { "type": "string", "example": "Engrave" }, "attribute_value": { "type": "string", "example": "Standard" } } } } } } }, "items_description": { "type": "string", "example": "2777228 1862500000 Acqua Colonia spray, 180ml." }, "total": { "type": "string", "example": "50.37" }, "status": { "type": "string", "example": "Unshipped" }, "name": { "type": "string", "example": "Mario Rossi" }, "company": { "type": "string", "example": "Company srl" }, "phone": { "type": "string", "example": "07809691234" }, "address": { "type": "string", "example": "123 Northumberland Road" }, "address2": { "type": "string", "example": "-" }, "postcode": { "type": "string", "example": "BS6 7BB" }, "city": { "type": "string", "example": "BRISTOL" }, "country": { "type": "string", "example": "GB" }, "state": { "type": [ "string", "null" ], "description": "State (string or null)." }, "email": { "type": "string", "example": "mario.rossi@gmail.com" }, "marketplace_platform": { "type": "string", "example": "Amazon" }, "marketplace_id": { "type": "string", "example": "123" }, "insurance": { "type": "string", "example": "0" }, "insuranceamount": { "type": "string", "example": "0" }, "shipment_amountpaid": { "type": "string", "example": "5.10" }, "payment_method": { "type": "string", "example": "Other" }, "note": { "type": "string", "example": "-" }, "user_note": { "type": [ "string", "null" ], "description": "User note (string or null)." }, "shippingservice": { "type": "string", "example": "Standard" }, "incoterm": { "type": "string", "example": "DAP" }, "billaccountno": { "type": [ "string", "null" ], "description": "Bill account number (string or null)." }, "archived": { "type": "string", "example": "0" }, "merged": { "type": "string", "example": "0" } } } } } }, "GetShippedOrdersParams": { "type": "object", "required": [ "DateMin", "DateMax" ], "properties": { "DateMin": { "type": "integer", "description": "Filter date from (Unix timestamp, seconds).", "example": 1489659960 }, "DateMax": { "type": "integer", "description": "Filter date to (Unix timestamp, seconds).", "example": 1573452677 }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number." }, "CarrierName": { "type": "string", "description": "Order carrier name." }, "OrderStatus": { "type": "string", "description": "Order status." }, "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs.", "items": { "type": "integer" } } } }, "GetShippedOrdersResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Total": { "type": "number", "example": 1 }, "Orders": { "type": "array", "description": "List of shipped orders.", "items": { "type": "object", "properties": { "ordine_id": { "type": "string", "example": "12333" }, "marketplace_platform": { "type": "string", "example": "Manual shipment" }, "marketplace_id": { "type": "string", "example": "0" }, "is_printed": { "type": "string", "example": "1" }, "transaction_id": { "type": "string", "example": "6351942" }, "to_address_street1": { "type": "string", "example": "Pestalozzistr. 1" }, "to_address_street2": { "type": "string", "example": "-" }, "to_address_city": { "type": "string", "example": "Obertshausen" }, "to_address_state": { "type": "string", "example": "ZZZ" }, "to_address_zip": { "type": "string", "example": "63179" }, "to_address_country": { "type": "string", "example": "DE" }, "to_address_name": { "type": "string", "example": "Maria Prek" }, "to_address_company": { "type": "string", "example": "-" }, "to_address_phone": { "type": "string", "example": "+123456789" }, "to_address_email": { "type": "string", "example": "customer@customer.com" }, "from_address_street1": { "type": "string", "example": "Via roma 2" }, "from_address_street2": { "type": "string", "example": "-" }, "from_address_city": { "type": "string", "example": "Firenze" }, "from_address_state": { "type": "string", "example": "FI" }, "from_address_zip": { "type": "string", "example": "50122" }, "from_address_country": { "type": "string", "example": "IT" }, "from_address_name": { "type": "string", "example": "ShippyPro" }, "from_address_company": { "type": "string", "example": "ShippyPro" }, "from_address_phone": { "type": "string", "example": "+3912345289" }, "from_address_email": { "type": "string", "example": "support@shippypro.com" }, "insurance": { "type": "string", "example": "0.00" }, "insurance_currency": { "type": "string", "example": "EUR" }, "cashondelivery": { "type": "string", "example": "0.00" }, "cashondelivery_currency": { "type": "string", "example": "EUR" }, "cashondelivery_type": { "type": "string", "example": "0" }, "label_pdf_url": { "type": "string", "example": "label-u90n7617719-15683693662.zpl" }, "tracking_code": { "type": "string", "example": "577945233758" }, "order_status": { "type": "string", "example": "1" }, "carrier_name": { "type": "string", "example": "DHLExpress" }, "carrier_id": { "type": "string", "example": "161" }, "service_name": { "type": "string", "example": "Express Domestic" }, "shipment_cost": { "type": "string", "example": "0" }, "shipment_cost_currency": { "type": "string", "example": "EUR" }, "created_at": { "type": "string", "example": "1568369357" }, "printed_at": { "type": "string", "example": "1568372012" }, "order_error_message": { "type": [ "string", "null" ], "description": "Order error message (null when none)." }, "total_sales": { "type": "string", "example": "57.95 EUR" }, "payment_method": { "type": "string", "example": "-" }, "archived": { "type": "string", "example": "1" }, "note": { "type": "string", "example": "-" }, "user_note": { "type": [ "string", "null" ], "description": "User note (null when none)." }, "carrier_note": { "type": "string", "example": "-" }, "incoterm": { "type": "string", "example": "DAP" }, "billaccountno": { "type": "string", "example": "0000" }, "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Nike shoes" }, "quantity": { "type": "string", "example": "1" }, "price": { "type": "string", "example": "20.50" }, "sku": { "type": "string", "example": "-" }, "asin": { "type": "string", "example": "-" } } }, "parcels": { "type": "object", "properties": { "weight": { "type": "number", "example": 1 }, "height": { "type": "number", "example": 5 }, "width": { "type": "number", "example": 5 }, "length": { "type": "number", "example": 5 } } } } } } } }, "DeletePendingOrderParams": { "type": "object", "required": [ "TransactionID" ], "properties": { "APIOrdersID": { "type": "integer", "description": "APIOrders Marketplace ID.", "example": 30 }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "030-9029737-3012345" } } }, "DeletePendingOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "`OK` if the call was successful, `NOK` otherwise.", "example": "OK" } } }, "IsPendingOrderParams": { "type": "object", "required": [ "TransactionID" ], "properties": { "MarketplacePlatform": { "type": "string", "description": "Order Marketplace platform.", "example": "Amazon" }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "030-9029737-3012345" } } }, "IsPendingOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Pending": { "type": "boolean", "description": "`true` if the order has not yet been shipped, or was shipped but the shipment failed.", "example": true } } }, "EditPendingOrdersParams": { "type": "object", "required": [ "Orders" ], "properties": { "Orders": { "type": "array", "description": "Pending orders to edit.", "items": { "type": "object", "properties": { "transaction_id": { "type": "string", "example": "030-9029737-3012345" }, "marketplace_platform": { "type": "string", "example": "Amazonv2" }, "marketplace_id": { "type": "string", "example": "1" }, "carrier_options": { "type": "array", "description": "Carrier-specific option name/value pairs.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "brtpoint" }, "value": { "type": "string", "example": "1" } } } } } } } } }, "EditPendingOrdersResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Total": { "type": "number", "example": 2 }, "Orders": { "type": "array", "description": "List of edited pending orders.", "items": { "type": "object", "description": "Order object.", "properties": { "transaction_id": { "type": "string", "example": "030-9029737-3012345" }, "marketplace_platform": { "type": "string", "example": "Amazonv2" }, "marketplace_id": { "type": "string", "example": "1" }, "result": { "type": "string", "example": "OK" }, "error_message": { "type": "string", "description": "Present only when `result` is `NOK`.", "example": "Pending order not found" } } } } } }, "PutShippedOrderParams": { "type": "object", "required": [ "to_address", "from_address", "parcels", "TransactionID", "ContentDescription", "ShipmentAmountPaid", "APIOrdersID", "Incoterm", "BillAccountNumber", "PaymentMethod", "CarrierName", "CarrierService", "CarrierID", "TrackingCode", "Track" ], "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "description": "Parcels information (minimum 1).", "items": { "description": "Containing items information", "type": "object", "required": [ "length", "width", "height", "weight" ], "properties": { "length": { "type": "number", "description": "Parcel length (in).", "example": 5 }, "width": { "type": "number", "description": "Parcel width (in).", "example": 5 }, "height": { "type": "number", "description": "Parcel height (in).", "example": 5 }, "weight": { "type": "number", "description": "Parcel weight (oz).", "example": 10 } } } }, "items": { "type": "array", "description": "Items contained in the order.", "items": { "description": "Containing items information", "type": "object", "properties": { "title": { "type": "string", "description": "Item title.", "example": "Acqua Colonia spray, 180ml." }, "imageurl": { "type": "string", "description": "URL for the item's image." }, "quantity": { "type": "integer", "description": "Quantity of items.", "example": 1 }, "price": { "type": "number", "description": "Price of items.", "example": 45.27 }, "sku": { "type": "string", "description": "SKU of items.", "example": "2777228_-1862500000" }, "ean": { "type": "string", "example": "3228170000000" }, "origin_country": { "type": "string", "description": "Country of origin for the item." }, "hs_code": { "type": "string", "description": "HS Code of the item." } } } }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number (max 255 chars).", "example": "ORDER2365" }, "Note": { "type": "string", "maxLength": 255, "description": "Additional notes (max 255 chars)." }, "ContentDescription": { "type": "string", "description": "Description of the content.", "example": "Milk" }, "TotalValue": { "type": "string", "description": "Value of the order including the currency (e.g. `120.50 EUR`). Required\nfor international shipments. The only accepted punctuation is `.` before\nthe decimal digits.\n", "example": "123 EUR" }, "ShipmentAmountPaid": { "type": "number", "description": "Amount paid for the shipment.", "example": 23.5 }, "APIOrdersID": { "type": "integer", "description": "APIOrders Marketplace ID.", "example": 12 }, "Incoterm": { "type": "string", "enum": [ "DAP", "DDP", "EXW" ], "description": "Shipment incoterm: DAP, DDP, or EXW. Defaults to DAP for cross-border shipments when unspecified.", "example": "DAP" }, "BillAccountNumber": { "type": "string", "description": "Bill the shipment to a third-party account number (default: '').", "example": "" }, "PaymentMethod": { "type": "string", "description": "Order payment method (e.g. Paypal, COD).", "example": "PayPal" }, "CarrierName": { "type": "string", "description": "Order carrier name.", "example": "DHLExpress" }, "CarrierService": { "type": "string", "description": "Order carrier service.", "example": "EXPRESS DOMESTIC" }, "CarrierID": { "type": "integer", "description": "Order carrier ID.", "example": 23 }, "CarrierNote": { "type": "string", "maxLength": 255, "description": "Carrier note (not supported by every carrier; max 255 chars)." }, "TrackingCode": { "type": "string", "description": "Order tracking code.", "example": "12345" }, "Track": { "type": "boolean", "description": "Set `true` to start tracking the shipment.", "example": false }, "Insurance": { "type": "number", "description": "Insurance value (default: 0)." }, "InsuranceCurrency": { "type": "string", "maxLength": 3, "description": "Insurance currency (default: EUR)." }, "ShipmentCost": { "type": "number", "description": "Selected rate value (default: 0)." }, "ShipmentCostCurrency": { "type": "string", "maxLength": 3, "description": "Selected rate currency (default: EUR)." }, "non_delivery_option": { "type": "string", "enum": [ "return", "abandon" ], "description": "Only for dutiable shipments. Accepted values: `return` (send back to sender), `abandon` (abandoned by consignee)." }, "IsReturn": { "type": "boolean", "description": "Set `true` if the order is a return." }, "Attributes": { "type": "object", "description": "One or more order attributes (`attribute-name`: `value`).", "additionalProperties": true }, "CN22Info": { "type": "array", "description": "Optional customs (CN22) line items.", "items": { "description": "Containing items information", "type": "object", "additionalProperties": true } } } }, "PutShippedOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "NewOrderID": { "type": "string", "example": "1234567" } } }, "GetPODParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "string", "description": "ShippyPro Order ID.", "example": "1224242" } } }, "GetPODResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "POD": { "type": "string", "description": "Base64-encoded Proof Of Delivery document.", "example": "JVBERi0xLjUKJfbk..." }, "FileType": { "type": "string", "example": "application/pdf" }, "CarrierName": { "type": "string", "example": "NEXIVE" } } }, "GetPODDocumentParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "string", "description": "ShippyPro Order ID.", "example": "1224242" } } }, "GetPODDocumentResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "`OK` if the document includes the POD signature, `PARTIAL_OK` if it was generated without one.", "example": "OK" }, "PODDocument": { "type": "string", "description": "Base64-encoded PDF containing the POD and shipment details.", "example": "JVBERi0xLjUKJfbk..." } } }, "GetDetailedPricingParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "string", "description": "ShippyPro Order ID.", "example": "1224242" } } }, "GetDetailedPricingResponse": { "type": "object", "properties": { "ZoneName": { "type": "string", "example": "BRT Italia" }, "WeightRange": { "type": "string", "example": "0-3" }, "DetailedPricing": { "type": "array", "description": "Per-component pricing breakdown.", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "tariff" }, "price": { "type": "number", "example": 6.34 }, "desc": { "type": "string", "example": "Tariff" } } } } } }, "CreateInvoiceParams": { "type": "object", "required": [ "DocumentType", "IncludeShippingCost", "Documents" ], "properties": { "DocumentType": { "type": "string", "description": "Specify `invoice` or `order_summary`.", "example": "invoice" }, "Prefix": { "type": "string", "description": "The prefix of the document name.", "example": "Prefix" }, "ProgressiveNumber": { "type": "integer", "description": "The progressive number from which the documents' numeration starts (default: 0).", "example": 1 }, "ShowLogo": { "type": "boolean", "description": "Set `true` if the company logo must be displayed in the invoice (default: false).", "example": false }, "IncludeShippingCost": { "type": "boolean", "description": "Set `true` if the shipping cost must be included in the invoice.", "example": true }, "VAT": { "type": "integer", "description": "VAT percentage (default: 0).", "example": 22 }, "UploadETD": { "type": "integer", "description": "Upload the document as Electronic Trade Document (default: false).", "example": 0 }, "Documents": { "type": "array", "description": "Array containing the documents' details (one object per order).", "items": { "type": "object", "required": [ "TransactionID", "MarketplacePlatform", "MarketplaceID", "Currency", "Date" ], "properties": { "VatNumber": { "type": "string", "description": "Customer's VAT number.", "example": "123" }, "AdditionalTaxID": { "type": "string", "description": "Customer's additional tax id.", "example": "1234" }, "AdditionalDescription": { "type": "string", "description": "Document additional description.", "example": "AdditionalDescription" }, "FooterDescription": { "type": "string", "description": "Document footer description.", "example": "FooterDescription" }, "OrderID": { "type": "integer", "description": "ShippyPro Order ID." }, "TransactionID": { "type": "string", "description": "Your internal reference order number (max 255 chars).", "example": "ORDER2365" }, "MarketplacePlatform": { "type": "string", "description": "Marketplace platform.", "example": "APIOrders" }, "MarketplaceID": { "type": "string", "description": "Marketplace ID.", "example": "1" }, "Currency": { "type": "string", "description": "Document currency.", "example": "EUR" }, "Date": { "type": "integer", "description": "Date timestamp (max 10 digits).", "example": 1653484662 } } } } } }, "CreateInvoiceResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Document": { "type": "array", "description": "Generated documents.", "items": { "type": "object", "properties": { "Base64": { "type": "string", "example": "JVBERi0xLjUKJfbk..." }, "Name": { "type": "string", "example": "Invoice_1.pdf" }, "Type": { "type": "string", "example": "invoice" } } } } } }, "MarkOrdersAsPrintedParams": { "type": "object", "required": [ "OrderIDS" ], "properties": { "OrderIDS": { "type": "array", "description": "ShippyPro Order IDs.", "items": { "type": "integer" }, "example": [ 12345 ] } } }, "MarkOrdersAsPrintedResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "GetShipmentsReportParams": { "type": "object", "required": [ "DateMin", "DateMax" ], "properties": { "DateMin": { "type": "integer", "description": "Filter date from, Unix timestamp in seconds (10 digits).", "example": 1489659960 }, "DateMax": { "type": "integer", "description": "Filter date to, Unix timestamp in seconds (10 digits).", "example": 1573452677 }, "Return": { "type": "boolean", "description": "Set `true` to view return shipments.", "example": false }, "IncludeItems": { "type": "boolean", "description": "Set `true` to include items in the response.", "example": true }, "ShowHiddenShipments": { "type": "boolean", "description": "Set `true` to include deleted orders.", "example": true } } }, "GetShipmentsReportResponse": { "type": "object", "properties": { "Shipments": { "type": "array", "description": "Shipments (and returns) generated in the timeframe.", "items": { "type": "object", "properties": { "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "otherFiscalId": { "type": "string", "description": "Sender fiscal ID, when available.", "example": "" } } } ] }, "parcels": { "type": "array", "description": "Parcels included in the shipment.", "items": { "type": "object", "properties": { "length": { "type": "number", "example": 5 }, "width": { "type": "number", "example": 5 }, "height": { "type": "number", "example": 5 }, "weight": { "type": "number", "example": 10 } } } }, "Items": { "type": "array", "description": "Order line items (present when `IncludeItems` is true).", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Acqua Colonia spray, 180ml." }, "quantity": { "type": "string", "example": "1" }, "price": { "type": "string", "example": "45.27" }, "sku": { "type": "string", "example": "2777228_-1862500000" }, "ean": { "type": "string", "example": "3228170000000" } } } }, "MarketplacePlatform": { "type": "string", "example": "Amazon" }, "TransactionID": { "type": "string", "example": "ORDER2365" }, "OrderID": { "type": "string", "example": "1234567" }, "CustomerReference": { "type": "string", "example": "a1234" }, "AccountNumber": { "type": "string", "example": "1X4834H0" }, "CarrierName": { "type": "string", "example": "DHLExpress" }, "CarrierService": { "type": "string", "example": "EXPRESS DOMESTIC" }, "TrackingNumber": { "type": "string", "example": "1ZA103756899507566" }, "TrackingExternalLink": { "type": "string", "example": "https://www.GenericCarrier.com?tracking_code=1ZA103756899507566" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have (e.g. multiparcel).", "items": { "type": "object", "properties": { "TrackingNumber": { "type": "string", "example": "1ZA10375689950756601" }, "TrackingExternalLink": { "type": "string", "example": "https://www.GenericCarrier.com?tracking_code=1ZA10375689950756601" } } } }, "Date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1696599902" }, "OrderStatus": { "type": "integer", "example": 1 }, "Hidden": { "type": "integer", "description": "`1` if the order is hidden/deleted, `0` otherwise.", "example": 0 }, "Incoterm": { "type": "string", "example": "DAP" }, "TotalValue": { "type": "string", "description": "Declared value with currency.", "example": "26.71 EUR" }, "insurance": { "type": "number", "example": 0 }, "insuranceCurrency": { "type": "string", "example": "EUR" }, "return": { "type": "boolean", "description": "`true` for return shipments.", "example": false }, "return_reason": { "type": "boolean", "example": false }, "shipment_cost": { "type": "number", "example": 4.2 } } } } } }, "GetReturnsReportParams": { "type": "object", "required": [ "DateMin", "DateMax" ], "properties": { "DateMin": { "type": "integer", "description": "Filter date from, Unix timestamp in seconds (10 digits).", "example": 1489659960 }, "DateMax": { "type": "integer", "description": "Filter date to, Unix timestamp in seconds (10 digits).", "example": 1573452677 } } }, "GetReturnsReportResponse": { "type": "object", "properties": { "Returns": { "type": "array", "description": "Returns generated in the timeframe.", "items": { "type": "object", "properties": { "Status": { "type": "string", "example": "0" }, "ReturnReason": { "type": "string", "example": "Too small" }, "Date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1556117640" }, "OriginalOrder": { "type": "object", "description": "The original outbound order.", "properties": { "MarketplacePlatform": { "type": "string", "example": "Shopify" }, "TransactionID": { "type": "string", "example": "1234567" }, "CarrierName": { "type": "string", "example": "Seur" }, "CarrierService": { "type": [ "string", "null" ], "example": null }, "TrackingNumber": { "type": "string", "example": "51_0431234567" }, "Date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1555500624" }, "from_address": { "$ref": "#/components/schemas/Address" }, "to_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "height": { "type": "number", "example": 20 }, "width": { "type": "number", "example": 20 }, "length": { "type": "number", "example": 20 }, "weight": { "type": "number", "example": 1 } } } }, "insurance": { "type": "string", "example": "0.00" }, "shipment_cost": { "type": "string", "example": "0" }, "attributes": { "type": "array", "description": "Free-form order attributes as name/value pairs.", "items": { "type": "object", "properties": { "attribute_name": { "type": "string", "example": "tags" }, "attribute_value": { "type": "string", "example": "Alixa::approved" } } } }, "Items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Camiseta Stone BLACK / L" }, "quantity": { "type": "string", "example": "1" }, "price": { "type": "string", "example": "20" }, "sku": { "type": "string", "example": "886608123456" }, "ean": { "type": "string", "example": "" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute_name": { "type": "string", "example": "tags" }, "attribute_value": { "type": "string", "example": "BEST;hierarchy:Hombre/Ropa/Camisetas" } } } } } } } } }, "ReturnOrder": { "type": "object", "description": "The return order.", "properties": { "MarketplacePlatform": { "type": "string", "example": "Returns" }, "TransactionID": { "type": "string", "example": "ShopifyS612345" }, "CarrierName": { "type": "string", "example": "Seur" }, "CarrierService": { "type": "string", "example": "Standard" }, "TrackingNumber": { "type": "string", "example": "91200181234567" }, "Date": { "type": "string", "description": "Unix timestamp (seconds), as a string.", "example": "1556110340" }, "from_address": { "$ref": "#/components/schemas/Address" }, "to_address": { "$ref": "#/components/schemas/Address" }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "height": { "type": "number", "example": 20 }, "width": { "type": "number", "example": 20 }, "length": { "type": "number", "example": 20 }, "weight": { "type": "number", "example": 1 } } } }, "insurance": { "type": "string", "example": "0.00" }, "shipment_cost": { "type": "string", "example": "0" }, "attributes": { "type": "array", "description": "Free-form order attributes as name/value pairs.", "items": { "type": "object", "properties": { "attribute_name": { "type": "string", "example": "tags" }, "attribute_value": { "type": "string", "example": "BEST;hierarchy:Hombre/Ropa/Camisetas" } } } } } } } } } } }, "CreateMasterShipmentParams": { "type": "object", "required": [ "CarrierID", "CarrierName" ], "properties": { "CarrierID": { "type": "integer", "description": "Carrier ID.", "example": 12345 }, "CarrierName": { "type": "string", "description": "Carrier name.", "example": "MyDHLBBX" } } }, "CreateMasterShipmentResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Data": { "type": "object", "description": "CreateMasterShipment response data.", "properties": { "CarrierName": { "type": "string", "example": "MyDHLBBX" }, "CarrierID": { "type": "number", "example": 1 }, "MasterShipmentID": { "type": "string", "example": "MYDHLBBX-MASTER-1-1683297829393" }, "CreatedAt": { "type": "string", "example": "Wed, 03 May 2023 11:31:42 +0200" } } } } }, "CloseMasterShipmentParams": { "type": "object", "description": "Closes a Bulk Shipping stream. Based on Ship โ€” only the differences are\nlisted here; every other parameter available with Ship can also be used.\n", "required": [ "masterShipmentId" ], "properties": { "masterShipmentId": { "type": "string", "description": "Master Shipment ID obtained from CreateMasterShipment.", "example": "MYDHLBBX-MASTER-1-1683297829393" }, "TotalValue": { "type": "string", "description": "Declared value with currency.", "example": "123 EUR" }, "CarrierName": { "type": "string", "example": "MyDHLBBX" }, "CarrierID": { "type": "integer", "example": 1 }, "to_address": { "$ref": "#/components/schemas/Address" }, "from_address": { "$ref": "#/components/schemas/Address" }, "Parcels": { "type": "array", "description": "Array of parcels (optional).", "items": { "type": "object", "additionalProperties": true } }, "CarrierOptions": { "type": "array", "description": "Carrier-specific option name/value pairs.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "mydhlbbxpallets" }, "value": { "type": "string", "example": "{\"1\":{\"length\":33,\"width\":33,\"height\":45,\"weight\":3}}" } } } }, "Async": { "type": "boolean", "example": false } } }, "CloseMasterShipmentResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "NewOrderID": { "type": "string", "example": "1234567" }, "LabelURL": { "description": "Label URL(s). An empty array (`[]`) when the order is in error, a\nsingle string when there is one label, or an array of strings when\nthere is more than one.\n", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": [ "https://cdn.shippypro.com/labels/first_label.zpl", "https://cdn.shippypro.com/labels/second_label.zpl" ] }, "PDF": { "type": "array", "description": "List of PDF labels.", "items": { "type": "string" } }, "ZPL": { "type": "array", "description": "List of ZPL labels.", "items": { "type": "string" } }, "TrackingCarrier": { "type": "string", "example": "MyDHLBBX" }, "TrackingNumber": { "type": "string", "example": "UD26123123456" }, "TrackingExternalLink": { "type": "string", "example": "https://mailingtechnology.com/tracking/?tn=UD26123123456" }, "AdditionalTrackingNumbers": { "type": "array", "description": "Additional tracking numbers/URLs the shipment may have (e.g. multiparcel).", "items": { "type": "object", "additionalProperties": true } }, "Status": { "type": "string", "description": "`1` if the label was generated correctly, `2` if an error occurred.", "example": "1" }, "ErrorMessage": { "type": "string", "description": "Carrier error message if an error occurred.", "example": "Error123" } } }, "GetPrintersParams": { "type": "object", "properties": { "ComputerHostname": { "type": "string", "description": "Search printers by computer name.", "example": "Main Computer" } } }, "GetPrintersResponse": { "type": "object", "properties": { "Printers": { "type": "array", "description": "List of connected printers.", "items": { "type": "object", "properties": { "PrinterID": { "type": "string", "example": "1489600800" }, "ComputerHostname": { "type": "string", "example": "Main Computer" }, "Name": { "type": "string", "example": "Zebra 500" } } } } } }, "PrintOrderParams": { "type": "object", "required": [ "OrderID" ], "properties": { "OrderID": { "type": "string", "description": "ShippyPro Order ID.", "example": "123456" }, "Force": { "type": "boolean", "description": "Force printing even if the order was already printed.", "default": false, "example": true }, "PrinterID": { "type": "string", "description": "If present, print on a specific printer ID; otherwise use the panel associations.", "example": "7890" } } }, "PrintOrderResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "OrderID": { "type": "string", "example": "123456" } } }, "PrintOrderBySKUParams": { "type": "object", "required": [ "SKU", "PickingListID" ], "properties": { "SKU": { "type": "string", "description": "Scanned item SKU.", "example": "SHOES1" }, "PickingListID": { "type": "integer", "description": "The Picking List number.", "example": 1 }, "Force": { "type": "boolean", "description": "Force printing even if the order was already printed.", "default": false, "example": false }, "PrinterID": { "type": "string", "description": "If present, print on a specific printer ID; otherwise use the panel associations.", "example": "7890" } } }, "PrintOrderBySKUResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "PrintResponses": { "type": "object", "description": "List of printed orders, keyed by ShippyPro order ID.", "additionalProperties": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "OrderID": { "type": "string", "example": "123456" } } } }, "MissingItems": { "type": "object", "description": "List of missing items, keyed by ShippyPro order ID then item ID.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sku": { "type": "string", "example": "missing item SKU" }, "title": { "type": "string", "example": "missing item title" }, "quantity": { "type": "string", "example": "1" }, "picked": { "type": "string", "example": "0" } } } } }, "AcknowledgedItem": { "type": "object", "description": "List of acknowledged items, keyed by ShippyPro order ID then item ID.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sku": { "type": "string", "example": "acknowledged item SKU" }, "title": { "type": "string", "example": "acknowledged item title" }, "quantity": { "type": "string", "example": "1" }, "picked": { "type": "string", "example": "0" } } } } } } }, "DropOffPoint": { "type": "object", "description": "A single Pick-Up & Drop-Off (PUDO) point.", "properties": { "PointID": { "type": "string", "example": "U83178036" }, "PointName": { "type": "string", "example": "MAIL BOXES ETC. 0345" }, "Latitude": { "type": "string", "example": "43.76750946" }, "Longitude": { "type": "string", "example": "11.25979900" }, "CarrierName": { "type": "string", "example": "UPS" }, "Street": { "type": "string", "example": "CORSO DEI TINTORI 39 ROSSO" }, "Zip": { "type": "string", "example": "50122" }, "City": { "type": "string", "example": "FIRENZE" }, "CountryCode": { "type": "string", "example": "IT" }, "State": { "type": "string", "example": "FI" }, "DistanceFromOrigin": { "type": "object", "description": "Distance of the point from the requested origin.", "properties": { "Value": { "type": "string", "example": "0.4" }, "UnitOfMeasurement": { "type": "object", "properties": { "Code": { "type": "string", "example": "KM" }, "Description": { "type": "string", "example": "KILOMETERS" } } } } }, "ImageURL": { "type": [ "string", "boolean" ], "description": "URL of the point image, or `false` when none is available.", "example": "https://www.ups.com/rms/image?id=6DF36446-39B0-4205-BDB2-31CC39DE238A" }, "Phone": { "type": "string", "example": "0230303039" }, "TypeOfPoint": { "type": [ "boolean", "string" ], "description": "Type of the point (e.g. `FMP`), or `false` when not applicable.", "example": false }, "DayOfWeek": { "type": "array", "description": "Opening hours per day of week.", "items": { "type": "object", "properties": { "Day": { "type": "string", "example": "2" }, "Hours": { "type": "array", "description": "Opening time ranges for the day.", "items": { "type": "string" }, "example": [ "9:30 - 13:00", "15:00 - 18:00" ] } } } } } }, "GetDropOffPointsParams": { "type": "object", "description": "Location filter for drop-off points. Provide **either** `city`/`zip`/`country`\n**or** `lat`/`lng`. Each set is individually optional, but at least one\ncomplete set must be supplied.\n", "properties": { "city": { "type": "string", "description": "Recipient city. Required if `lat`/`lng` are not provided.", "example": "Florence" }, "zip": { "type": "string", "description": "Recipient zip code. Required if `lat`/`lng` are not provided.", "example": "50126" }, "country": { "type": "string", "description": "Recipient country. Required if `lat`/`lng` are not provided.", "example": "IT" }, "couriers": { "type": "array", "description": "Carriers to display.", "items": { "type": "string" }, "example": [ "UPS", "POSTEITALIANE" ] }, "limit": { "type": "integer", "description": "Maximum number of drop-off points, up to 50 (default 20).", "example": 20 }, "range": { "type": "integer", "description": "Search area range in km (min 1, max 20).", "example": 10 }, "lat": { "type": "number", "description": "Latitude. Can be used with `lng` as an alternative to `city`/`zip`/`country`.", "example": 43.7675 }, "lng": { "type": "number", "description": "Longitude. Can be used with `lat` as an alternative to `city`/`zip`/`country`.", "example": 11.2597 } } }, "GetDropOffPointsResponse": { "type": "object", "properties": { "Result": { "type": "string", "description": "`OK` when all carriers succeeded, `PARTIAL_OK` when some failed (see `Warnings`), `NOK` on request-level errors (see `Error`).", "example": "OK" }, "Points": { "type": "object", "description": "Drop-off points grouped by carrier name. Each value is an array of points (possibly empty if a carrier has no nearby points).", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/DropOffPoint" } } }, "Warnings": { "type": "object", "description": "Present only when `Result` is `PARTIAL_OK`. Keyed by carrier name; the value `service_unavailable` indicates the service could not fetch points for that carrier, which is then absent from `Points`.", "additionalProperties": { "type": "string" }, "example": { "POSTEITALIANE": "service_unavailable" } }, "Error": { "type": "string", "description": "Present only when `Result` is `NOK`. Request-level error message.", "example": "Missing required parameters: provide either (zip, city, country) or (lat, lng)" } } }, "GetDropOffInfoParams": { "type": "object", "required": [ "PointId", "CarrierName" ], "properties": { "PointId": { "type": "string", "description": "Point id to be searched.", "example": "U83178036" }, "CarrierName": { "type": "string", "description": "The carrier name that the point belongs to.", "example": "UPSv2" }, "Country": { "type": "string", "description": "Point country.", "example": "IT" }, "CarrierId": { "type": "integer", "description": "The carrier id to use to search for the point.", "example": 1 } } }, "GetDropOffInfoResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "DropOff": { "type": "array", "description": "Detailed information for the requested drop-off point.", "items": { "$ref": "#/components/schemas/DropOffPoint" } }, "Errors": { "type": "object", "additionalProperties": true } } }, "GetLoginTokenParams": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "description": "Username used for login.", "example": "mario.rossi@gmail.com" }, "password": { "type": "string", "description": "Password used for login.", "example": "abcd1234" } } }, "GetLoginTokenResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "tokenUrl": { "type": "string", "description": "Impersonation login URL containing the access token.", "example": "https://www.shippypro.com/login.html?impersonatetoken=myResponseToken" } } }, "RegisterNewUserParams": { "type": "object", "description": "All parameters must be included in the request; the invoice, whitelabel\nand account-setup fields may be sent empty.\n", "required": [ "customer_name", "customer_surname", "customer_email", "customer_company", "customer_phone", "customer_street", "customer_housenr", "customer_zip", "customer_city", "customer_country", "customer_vatno", "customer_state", "customer_otherfiscalid", "customer_invoice_name", "customer_invoice_surname", "customer_invoice_email", "customer_invoice_company", "customer_invoice_phone", "customer_invoice_street", "customer_invoice_housenr", "customer_invoice_zip", "customer_invoice_city", "customer_invoice_country", "customer_invoice_vatno", "customer_invoice_state", "customer_invoice_otherfiscalid", "customer_avatar_url", "customer_whitelabel_clientref", "customer_whitelabel_paywithcredits", "customer_show_net_rates", "wholesaler", "eori", "ioss", "create_apiorders", "create_apikey" ], "properties": { "customer_name": { "type": "string", "description": "Client's name.", "example": "Mario" }, "customer_surname": { "type": "string", "description": "Client's surname.", "example": "Rossi" }, "customer_email": { "type": "string", "description": "Client's email.", "example": "mario.rossi@gmail.com" }, "customer_company": { "type": "string", "description": "Client's company.", "example": "Nintendo" }, "customer_phone": { "type": "string", "description": "Client's phone.", "example": "07809691234" }, "customer_street": { "type": "string", "description": "Client's street.", "example": "Northumberland Road" }, "customer_housenr": { "type": "string", "description": "Client's house number.", "example": "123" }, "customer_zip": { "type": "string", "description": "Client's zip code.", "example": "BS6 7BB" }, "customer_city": { "type": "string", "description": "Client's city.", "example": "BRISTOL" }, "customer_country": { "type": "string", "description": "Client's country (ISO 3166).", "example": "GB" }, "customer_vatno": { "type": "string", "description": "Client's VAT number.", "example": "1234567890" }, "customer_state": { "type": "string", "description": "Client's state.", "example": "United Kingdom" }, "customer_otherfiscalid": { "type": "string", "description": "Client's fiscal code.", "example": "RSSMRA95A01H501B" }, "customer_invoice_name": { "type": "string", "description": "Customer name for the invoice (may be empty).", "example": "" }, "customer_invoice_surname": { "type": "string", "description": "Customer surname for the invoice (may be empty).", "example": "" }, "customer_invoice_email": { "type": "string", "description": "Customer email for the invoice (may be empty).", "example": "" }, "customer_invoice_company": { "type": "string", "description": "Customer company for the invoice (may be empty).", "example": "" }, "customer_invoice_phone": { "type": "string", "description": "Customer phone for the invoice (may be empty).", "example": "" }, "customer_invoice_street": { "type": "string", "description": "Customer street for the invoice (may be empty).", "example": "" }, "customer_invoice_housenr": { "type": "string", "description": "Customer house number for the invoice (may be empty).", "example": "" }, "customer_invoice_zip": { "type": "string", "description": "Customer zip for the invoice (may be empty).", "example": "" }, "customer_invoice_city": { "type": "string", "description": "Customer city for the invoice (may be empty).", "example": "" }, "customer_invoice_country": { "type": "string", "description": "Customer country for the invoice (may be empty).", "example": "" }, "customer_invoice_vatno": { "type": "string", "description": "Customer VAT number for the invoice (may be empty).", "example": "" }, "customer_invoice_state": { "type": "string", "description": "Customer state for the invoice (may be empty).", "example": "" }, "customer_invoice_otherfiscalid": { "type": "string", "description": "Customer fiscal code for the invoice (may be empty).", "example": "" }, "customer_avatar_url": { "type": "string", "description": "Client's avatar url (may be empty).", "example": "https://www.mariorossi.uk/img.jpg" }, "customer_whitelabel_clientref": { "type": "string", "description": "Client's reference (may be empty).", "example": "a1234" }, "customer_whitelabel_paywithcredits": { "type": "integer", "description": "Whether the customer pays shipments with credits.", "example": 0 }, "customer_show_net_rates": { "type": "integer", "description": "Whether to show tariffs with VAT or not.", "example": 0 }, "wholesaler": { "type": "boolean", "description": "Whether the customer is a wholesaler.", "example": false }, "eori": { "type": "string", "description": "Client's EORI (may be empty).", "example": "GB123456123000" }, "ioss": { "type": "string", "description": "Client's IOSS (may be empty).", "example": "IM1234123890" }, "create_apiorders": { "type": "integer", "description": "Whether the APIOrders marketplace is automatically connected.", "example": 1 }, "create_apikey": { "type": "boolean", "description": "Whether API keys are generated.", "example": true } } }, "RegisterNewUserResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" }, "Username": { "type": "string", "example": "mario.rossi@gmail.com" }, "Password": { "type": "string", "example": "abcd1234" }, "APIOrdersID": { "type": "string", "description": "Identifier of the created APIOrders marketplace connection.", "example": "1" } } }, "BlockUserParams": { "type": "object", "required": [ "customer_email" ], "properties": { "customer_email": { "type": "string", "description": "Customer email.", "example": "user@example.com" }, "message": { "type": "string", "description": "Optional message.", "example": "" } } }, "BlockUserResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "UnblockUserParams": { "type": "object", "required": [ "customer_email" ], "properties": { "customer_email": { "type": "string", "description": "Customer email.", "example": "user@example.com" }, "message": { "type": "string", "description": "Optional message.", "example": "" } } }, "UnblockUserResponse": { "type": "object", "properties": { "Result": { "type": "string", "example": "OK" } } }, "GetCustomersParams": { "type": "object", "description": "No parameters.", "additionalProperties": false }, "GetCustomersResponse": { "type": "object", "properties": { "Customers": { "type": "array", "description": "List of customers.", "items": { "type": "object", "properties": { "FirstName": { "type": "string", "example": "Mario" }, "LastName": { "type": "string", "example": "Rossi" }, "Company": { "type": "string", "example": "Nintendo" }, "Email": { "type": "string", "example": "mario.rossi@gmail.com" }, "Telephone": { "type": "string", "example": "07809691234" }, "Street": { "type": "string", "example": "Northumberland Road" }, "HouseNumber": { "type": "string", "example": "123" }, "Postcode": { "type": "string", "example": "BS6 7BB" }, "City": { "type": "string", "example": "BRISTOL" }, "State": { "type": "string", "example": "United Kingdom" }, "Country": { "type": "string", "example": "GB" }, "VatNumber": { "type": "string", "example": "1234567890" }, "OtherFiscalID": { "type": "string", "example": "RSSMRA95A01H501B" }, "CustomerReference": { "type": "string", "example": "a1234" } } } } } }, "TrackingUpdateEvent": { "type": "object", "description": "Payload delivered to your callback URL for a tracking update.", "properties": { "Event": { "description": "Event name: TRACKING_UPDATE", "type": "string", "const": "TRACKING_UPDATE" }, "tracking": { "type": "string", "description": "Tracking number.", "example": "1ZA103756899507566" }, "date": { "type": "integer", "description": "Event date (Unix timestamp, seconds).", "example": 1489659960 }, "message": { "type": "string", "description": "Event description.", "example": "DELIVERED" }, "city": { "description": "City where the event happened", "type": "string", "example": "MOTRIL" }, "est_delivery_date": { "type": "string", "maxLength": 10, "description": "Estimated delivery date (Unix timestamp as string). Returned only\nfor carriers that support Live Rates; for other carriers ShippyPro\ncan still calculate it if delivery times are set manually in the\nCarrier Connection Price page, otherwise 0 is returned.\n", "example": "1489659960" }, "first_status_date": { "type": "string", "maxLength": 10, "description": "First event status date (Unix timestamp as string).", "example": "1489646578" }, "late": { "type": "string", "description": "\"1\" if the shipment is late.", "example": "0" }, "code": { "type": "integer", "description": "ShippyPro tracking status code:\n`0` In Preparation, `1` Info Received, `2` In Transit,\n`3` Out for Delivery, `4` Missed Delivery, `5` Exception, `6` Delivered.\n", "enum": [ 0, 1, 2, 3, 4, 5, 6 ], "example": 6 }, "extendedCode": { "type": [ "string", "null" ], "description": "Extended (granular) tracking status code." }, "OrderID": { "description": "ShippyPro Order ID", "type": "string", "example": "191252" }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "ORDER2365" }, "TrackingCarrier": { "description": "Carrier name", "type": "string", "example": "UPS" }, "TrackingCarrierID": { "description": "Carrier ID", "type": "string", "example": "123" }, "MarketplaceID": { "description": "Marketplace ID", "type": "string", "example": "123" }, "MarketplacePlatform": { "description": "Marketplace name", "type": "string", "example": "Amazon" }, "IsReturn": { "type": "boolean", "description": "True if the order is a return.", "example": false }, "ReturnType": { "type": [ "string", "null" ], "description": "Return type: manual_return, return_label_combination, easy_return, or null if not a return." }, "ExternalLink": { "type": "string", "description": "Carrier tracking link.", "example": "https://www.carrierwebsite.com/tracking/123" }, "IsReturning": { "type": "boolean", "description": "True only if the order receives a delivery exception and will be returned to sender." }, "ReturnTrackingNumber": { "type": "string", "description": "Return tracking number of a Return Label in the Box shipment." }, "AtPudo": { "type": "boolean", "description": "True if the order is at a PUDO point." }, "PudoID": { "type": "string", "description": "PUDO point identifier." }, "Category": { "type": "string", "description": "For tracking exceptions, the exception category." }, "Attributes": { "type": "object", "description": "Order attribute values, if defined on the order.", "additionalProperties": true } } }, "OrderShippedEvent": { "type": "object", "description": "Payload delivered to your callback URL when an order is shipped.", "properties": { "Event": { "description": "Event name: ORDER_SHIPPED", "type": "string", "const": "ORDER_SHIPPED" }, "LabelURL": { "type": "array", "description": "Label URLs.", "items": { "type": "string" }, "example": [ "https://www.shippypro.com/ldv/ldv-1.pdf", "https://www.shippypro.com/ldv/ldv-2.pdf" ] }, "OrderID": { "description": "ShippyPro Order ID", "type": "string", "example": "191252" }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "ORDER2365" }, "CarrierID": { "description": "Carrier ID", "type": "integer", "example": 50 }, "TrackingCarrier": { "description": "Tracking Carrier", "type": "string", "example": "UPS" }, "TrackingNumber": { "description": "Tracking number", "type": "string", "example": "1ZA103756899507566" }, "MarketplaceID": { "description": "Marketplace ID", "type": "string", "example": "123" }, "MarketplacePlatform": { "description": "Marketplace name", "type": "string", "example": "Amazon" }, "IsReturn": { "type": "boolean", "description": "True if the order is a return. For Return Label in the Box shipments this is sent as false.", "example": false }, "ReturnType": { "type": [ "string", "null" ], "description": "Return type: manual_return, return_label_combination, easy_return, or null if not a return." }, "ReturnTrackingNumber": { "type": "string", "description": "Return tracking number of a Return Label in the Box shipment." }, "Attributes": { "type": "object", "description": "Custom order attributes.", "additionalProperties": true } } }, "OrderErrorEvent": { "type": "object", "description": "Payload delivered to your callback URL when an order errors.", "properties": { "Event": { "description": "Event name: ORDER_ERROR", "type": "string", "const": "ORDER_ERROR" }, "OrderID": { "description": "ShippyPro Order ID", "type": "string", "example": "191252" }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "ORDER2365" }, "ErrorMessage": { "description": "Error message description", "type": "string", "example": "Street too long" }, "ErrorType": { "$ref": "#/components/schemas/ErrorType" }, "ErrorSuggestion": { "$ref": "#/components/schemas/ErrorSuggestion" } } }, "ReturnLabelInTheBoxTrackingUpdateEvent": { "type": "object", "description": "Payload delivered to your callback URL for a Return Label in the Box tracking update.", "properties": { "Event": { "description": "Event name: RETURN_LABEL_IN_THE_BOX_TRACKING_UPDATE", "type": "string", "const": "RETURN_LABEL_IN_THE_BOX_TRACKING_UPDATE" }, "tracking": { "description": "Tracking number", "type": "string", "example": "1ZA103756899507566" }, "date": { "type": "integer", "description": "Event date (Unix timestamp, seconds).", "example": 1489659960 }, "message": { "description": "Event description", "type": "string", "example": "DELIVERED" }, "city": { "description": "City where the event happened", "type": "string", "example": "MOTRIL" }, "code": { "type": "integer", "description": "ShippyPro tracking status code:\n`1` Info Received, `2` In Transit, `3` Out for Delivery,\n`4` Missed Delivery, `5` Exception, `6` Delivered.\n", "enum": [ 1, 2, 3, 4, 5, 6 ], "example": 6 }, "OrderID": { "description": "ShippyPro Order ID", "type": "string", "example": "191252" }, "TransactionID": { "type": "string", "maxLength": 255, "description": "Your internal reference order number.", "example": "ORDER2365" }, "TrackingCarrier": { "description": "Carrier name", "type": "string", "example": "UPS" }, "TrackingCarrierID": { "description": "Carrier ID", "type": "string", "example": "123" }, "MarketplaceID": { "description": "Marketplace ID", "type": "string", "example": "123" }, "MarketplacePlatform": { "description": "Marketplace name", "type": "string", "example": "Amazon" } } } }, "responses": { "BadRequest": { "description": "Bad Request - The request could not be understood or was missing the required parameters." }, "Unauthorized": { "description": "Unauthorized - Authentication failed or the user does not have permissions for the requested operation." }, "Forbidden": { "description": "Forbidden - Access denied." }, "NotFound": { "description": "Not Found - Resource was not found." }, "TooManyRequests": { "description": "Too Many Requests - Rate limit exceeded (20 API requests every 10 seconds)." }, "InternalError": { "description": "Internal Server Error - ShippyPro has encountered an error." } } } }