# InPost InPost ShipX integration with Ritevo: API token and organization ID, parcel size and drop-off method, parcel locker shipments with cash on delivery, labels, reconnecting. The InPost integration creates parcel locker shipments through the InPost ShipX API. You connect it with an API token and an organization ID from InPost's Manager Paczek (parcel manager). > **Required integration:** You need an InPost Manager Paczek account with the company and invoice details filled in. You can add as many InPost integrations as you like, including several for the same account - for example with a different label format, parcel or sender address. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is not used. You provide a new token with `PATCH /integrations/shippings/inpost-locker-x/{id}/token` - in any state of the integration. It checks the token in InPost and sets `authError=false` and `active=true`. ## Which shipments it creates - **Parcel locker** - the shipment always goes to the parcel locker the buyer chose. The order must have a pickup point - without it InPost rejects the shipment. - **Courier** - courier shipments are not supported. - **Allegro orders** - get the Paczkomat Allegro service, the others the standard Paczkomat service. - **Cash on delivery and insurance** - cash on delivery from the order, insurance from the integration settings. - **Any sales channel** - you can create a shipment for an order from any channel. ## Where to find the token and the organization ID You will find both in InPost's Manager Paczek. Have them ready before adding the integration: 1. Sign in to InPost's Manager Paczek at manager.paczkomaty.pl. 2. Go to **Moje konto** → **API** (my account, API) and in the **API ShipX** tab click **Generuj** (generate). Copy the token. 3. In the **Ustawienia organizacji** (organization settings) tab copy the organization ID. It only shows up after the token is generated. ## Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Shipments** section pick the **Inpost paczkomat ShipX** tile. 3. Enter the **Account name** - your own name for the integration - and paste the **ShipX API token** and the **ShipX organization ID**. 4. Fill in the other settings described below and click **Add integration**. We check the token in InPost right away: if it is wrong, you will see the error returned by InPost and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Inpost paczkomat ShipX tile framed in the Shipments section](https://ritevo.com/docs/integrations/inpost/en-catalogue.webp) ![The InPost add screen with Account name, ShipX API token, ShipX organization ID, parcel size, label format, drop-off method and point code fields](https://ritevo.com/docs/integrations/inpost/en-add.webp) ## Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. - **Default parcel size** - **Size A**, **Size B** or **Size C**. A by default. - **Label format** - A4 PDF, A6 PDF, A6 ZPL, A6 ZPL 300dpi or A6 EPL. A6 PDF by default. - **Drop-off method** - how you hand parcels over to InPost: **Courier pickup**, **Drop-off at a Paczkomat locker**, **Drop-off at an InPost branch**, **Drop-off at a POK**, **Drop-off at a POP (PaczkoPunkt)** or **Drop-off at any point**. Courier pickup by default. - **Drop-off point code** - the code of the point where you drop off parcels. The field is required for every drop-off method. - **Update token** - you enter a new ShipX API token. - **Sender address on the label** - the sender details the carrier prints on the label. - **Courier pickup address** - the address the courier collects parcels from. It can differ from the sender address on the label - for example in dropshipping: the label shows your shop, and the courier collects the parcel from the wholesaler. - **Additional insurance** - the insurance amount of every shipment: **None**, **Order value with delivery**, **Order value without delivery** or **Fixed amount**. In **Currency source** you pick the order currency, the delivery country currency or a fixed currency. Integration fields: `accountName`, `apiToken`, `organizationId`, `defaultTemplate` (**Size A** = `SMALL`, **Size B** = `MEDIUM`, **Size C** = `LARGE`), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_ZPL_300`, `A6_EPL`), `sendingMethod` (**Courier pickup** = `DISPATCH_ORDER`, **Drop-off at a Paczkomat locker** = `PARCEL_LOCKER`, **Drop-off at an InPost branch** = `BRANCH`, **Drop-off at a POK** = `POK`, **Drop-off at a POP (PaczkoPunkt)** = `POP`, **Drop-off at any point** = `ANY_POINT`) and `dropoffPoint`. Fields shared by shipping integrations: `senderAddress` and `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) and `additionalInsurance`. In it `insuranceType`: **None** = `NONE`, **Order value with delivery** = `ORDER_AMOUNT_WITH_DELIVERY`, **Order value without delivery** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Fixed amount** = `FIXED_AMOUNT` (amount in `fixedAmount`), and `currencySource`: **Order currency** = `ORDER_CURRENCY`, **Delivery country currency** = `DELIVERY_COUNTRY_CURRENCY`, **Fixed currency** = `FIXED` (currency in `fixedCurrency`, required with `FIXED`). ![InPost integration details: basic settings with parcel size, label format, drop-off method and point code, and the sender address](https://ritevo.com/docs/integrations/inpost/en-details.webp) ![The Sender address on the label card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-sender.webp) ![The Courier pickup address card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-pickup-address.webp) ![The Additional insurance card with the Insurance type and Currency source fields](https://ritevo.com/docs/integrations/shipping/en-insurance.webp) > **Good to know:** The integration does not book a courier pickup. You book the pickup directly with the carrier or set up a regular pickup schedule with them. > **Good to know:** When the order's payment method is **Cash on delivery**, the shipment gets cash on delivery automatically - in the order's amount and currency. ## Creating shipments You create a shipment from the order in two ways: - **By hand** - in the order details, in the **Shipments** card, click the button with the InPost integration name. You only see buttons for active integrations that match the order. - **Automatically** - with the **Create shipment** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The shipment details come from the order: - **Recipient** - the order's delivery address and the buyer's phone and email. - **Pickup point** - the point the buyer chose, if the order has one. - **Cash on delivery** - the amount to pay from the order, when the payment method is **Cash on delivery**. - **Parcel** - one shipment is always one parcel. In the same card every shipment has a tracking number, a state and a creation date. The states: - **Being created** (API: "Being created" = `PENDING`; value in `shipments[].status`) - the carrier is still creating the shipment. We check it every few seconds. If the carrier does not confirm the shipment within 24 hours, it ends with an error. - **Created successfully** (API: "Created successfully" = `SUCCESS`; value in `shipments[].status`) - the shipment is with the carrier and has a tracking number. - **Creation failed** (API: "Creation failed" = `ERROR`; value in `shipments[].status`) - the carrier did not accept the shipment. The reason is shown next to the state, and for a carrier error also the carrier's message. You download the label of a created shipment with the **Download** button in the **Shipments** card. You print it in two ways - the [Ritevo Printer](https://ritevo.com/en/docs/integrations/ritevo-printer) app must run on the computer with the printer: - **By hand** - in the **Shipments** card click **Print** and pick the printer. - **Automatically** - with the **Print shipment label** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The step prints the label of the latest shipment in the **Created successfully** state - it skips shipments being created and failed ones. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. > **Good to know:** Every button click and every run of the **Create shipment** step creates a new shipment with the carrier. A shipment cannot be cancelled in Ritevo - you cancel it in the carrier's panel. ### How a shipment reaches InPost - **Confirmation** - InPost creates the shipment in the background, so at first it is **Being created**. When InPost assigns the tracking number, it changes to **Created successfully**. - **Tracking number** - the InPost shipment number. The same number is on the label. - **Cancelled in InPost** - a shipment cancelled in InPost while being created ends with an error. You create a shipment with `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - the response is 202, and the result shows up later in the order's `shipments[]` (`status`, `trackingNumber`, `errorType`, `errorMessage`). You download the label with `GET /orders/{orderId}/shipments/{shipmentId}/label` and request printing with `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Order actions: the **Create shipment** step is `CREATE_SHIPMENT` and **Print shipment label** is `PRINT_SHIPMENT_LABEL` - both in `actionSteps[].action.type`, with `uuidValue` = the shipping integration id (`GET /integrations/shippings`) or the printer id (`GET /integrations/printers`). The **Shipment created** trigger is `triggerType` = `CREATE_SHIPMENT`. Conditions: **Has shipment** / **Has no shipment** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Shipment status is** / **Shipment status is not** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Shipment belongs to integration** / **Shipment does not belong to integration** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = shipping integration ids). The print step in an action takes the newest shipment with `status` = `SUCCESS` (by `createdAt`); manual printing via `POST /orders/{orderId}/print-shipment-label/...` also accepts only a `SUCCESS` shipment and returns `SHIPMENT_NOT_FOUND` otherwise. `SHIPMENT_STATUS_IS` is met when any shipment of the order has the given status, not only the latest. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ## Reconnection required This state shows up when InPost stops accepting the token - for example after a new token was generated in Manager Paczek. Until you enter a new token you cannot create shipments or download labels. 1. Copy the current token from the **API ShipX** tab in InPost's Manager Paczek. 2. On the integration page click **Update token**, paste it into the **New ShipX API token** field and confirm. We check it in InPost the same way as when adding - a valid one refreshes the connection, and the settings stay unchanged. ![The bottom of the InPost integration page with the Update token and Update integration buttons](https://ritevo.com/docs/integrations/inpost/en-token.webp) ![The Update token window of the InPost integration with the New ShipX API token field](https://ritevo.com/docs/integrations/inpost/en-update-token.webp) > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ## Deleting the integration **Delete integration** turns the integration off in Ritevo. Shipments created earlier stay in the orders and with the carrier. **Restore integration** turns it back on. ## What the integration does not do - It does not book a courier pickup. - It does not cancel shipments. - It does not track a shipment after it is created - you check the delivery state with the carrier. - It does not send the tracking number to the sales channel. - It does not create shipments with several parcels. - It does not create courier shipments - parcel lockers only. ## The integration through the API This integration's endpoints are under `/integrations/shippings/inpost-locker-x`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/shippings`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.