> ## Documentation Index > Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a return shipment intent > Create the RETURN_SHIPMENT task of an offboarding: the parcel that brings the leaver devices back. The device handling usually opens it on execute; create one only when it did not. A field you leave out is pre-filled from the leaver, the company and the device handling. The intent holds the `createShipment` input: the pickup address (the leaver home by default), the destination (the company first address by default), the parcel, the declared value, the content, the billing profile (`getBillingProfiles`). Returns the intent `id`, its `taskId` and the `ticketId` holding it. The task cannot be marked done by hand: `updateTaskStatus` refuses it with `TaskLockedByTypeError`, and it completes when the intent executes. The offboarding opens this task itself (`createOffboarding`); its `intentId` is on the task (`getTicket`). Create one only for a step the offboarding did not open. `createTicket` and `createTask` cannot make a typed task. Refused with `OFFBOARDING_NOT_FOUND`, `PARENT_TICKET_NOT_FOUND`, `PARENT_TICKET_IS_TYPED` or `PARENT_TICKET_IS_A_TASK` (pass the untyped ticket instead), `OFFBOARDING_NOT_OPEN`, `BILLING_PROFILE_NOT_FOUND`. Key: WriteScope: Company ## OpenAPI ````yaml https://api.getprimo.com/openapi.json post /return-shipment-intents openapi: 3.1.1 info: title: Public API - BETA description: Read docs on https://docs.getprimo.com/ version: '1.0' contact: {} servers: - url: https://api.getprimo.com security: - apikey: [] tags: [] paths: /return-shipment-intents: post: tags: - Offboardings summary: Create a return shipment intent description: >- Create the RETURN_SHIPMENT task of an offboarding: the parcel that brings the leaver devices back. The device handling usually opens it on execute; create one only when it did not. A field you leave out is pre-filled from the leaver, the company and the device handling. The intent holds the `createShipment` input: the pickup address (the leaver home by default), the destination (the company first address by default), the parcel, the declared value, the content, the billing profile (`getBillingProfiles`). Returns the intent `id`, its `taskId` and the `ticketId` holding it. The task cannot be marked done by hand: `updateTaskStatus` refuses it with `TaskLockedByTypeError`, and it completes when the intent executes. The offboarding opens this task itself (`createOffboarding`); its `intentId` is on the task (`getTicket`). Create one only for a step the offboarding did not open. `createTicket` and `createTask` cannot make a typed task. Refused with `OFFBOARDING_NOT_FOUND`, `PARENT_TICKET_NOT_FOUND`, `PARENT_TICKET_IS_TYPED` or `PARENT_TICKET_IS_A_TASK` (pass the untyped ticket instead), `OFFBOARDING_NOT_OPEN`, `BILLING_PROFILE_NOT_FOUND`. operationId: createReturnShipmentIntent parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReturnShipmentIntentBody' responses: default: description: '' content: application/json: schema: $ref: '#/components/schemas/ReturnShipmentIntent_Output' components: schemas: CreateReturnShipmentIntentBody: type: object properties: fromAddress: description: Where the parcel is picked up, by default the leaver's address anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string minLength: 1 complement: anyOf: - type: string - type: 'null' postalCode: type: string minLength: 1 city: type: string minLength: 1 country: anyOf: - type: string - type: 'null' countryCode: description: ISO 3166-1 alpha-2 anyOf: - type: string - type: 'null' type: anyOf: - type: string enum: - HOME - WORK - type: 'null' required: - street - postalCode - city - type: 'null' toAddress: description: Where it goes, by default the company's first address anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string minLength: 1 complement: anyOf: - type: string - type: 'null' postalCode: type: string minLength: 1 city: type: string minLength: 1 country: anyOf: - type: string - type: 'null' countryCode: description: ISO 3166-1 alpha-2 anyOf: - type: string - type: 'null' type: anyOf: - type: string enum: - HOME - WORK - type: 'null' required: - street - postalCode - city - type: 'null' createBoxShipment: description: Send a Primo box to the leaver first anyOf: - type: boolean - type: 'null' parcel: anyOf: - type: object properties: weight: description: Grams type: integer minimum: 100 maximum: 20000 length: description: Millimetres type: integer minimum: 10 maximum: 1000 width: description: Millimetres type: integer minimum: 10 maximum: 1000 height: description: Millimetres type: integer minimum: 10 maximum: 1000 required: - weight - length - width - height - type: 'null' hasInsurance: anyOf: - type: boolean - type: 'null' value: description: 'Declared value of the content, in cents: 150000 for €1,500' anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' content: description: What goes back; replaced whole anyOf: - type: array items: type: object properties: id: description: The device or accessory id, when the item is one anyOf: - type: string pattern: ^[a-f\d]{24}$ - type: 'null' name: type: string type: anyOf: - type: string - type: 'null' required: - name - type: 'null' billingProfileId: description: From `getBillingProfiles` anyOf: - type: string pattern: ^[a-f\d]{24}$ - type: 'null' notificationEmails: anyOf: - type: array items: type: string minLength: 1 - type: 'null' comment: anyOf: - type: string - type: 'null' offboardingId: description: The offboarding this step belongs to, from `getOffboardings` type: string pattern: ^[a-f\d]{24}$ parentTicketId: description: >- The ticket to hold the task. Defaults to the offboarding ticket; never a typed task. anyOf: - type: string pattern: ^[a-f\d]{24}$ - type: 'null' required: - offboardingId ReturnShipmentIntent_Output: type: object properties: id: type: string description: Intent id, to pass to its update and execute tools taskId: description: The typed task that tracks this step anyOf: - type: string - type: 'null' ticketId: description: >- The ticket holding that task, usually the offboarding ticket. Null if it could not be read back. anyOf: - type: string - type: 'null' offboardingId: type: string executedAt: description: When the intent executed; null until then anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' fromAddress: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string complement: anyOf: - type: string - type: 'null' postalCode: type: string city: type: string country: anyOf: - type: string - type: 'null' countryCode: anyOf: - type: string - type: 'null' type: anyOf: - type: string enum: - HOME - WORK - type: 'null' required: - name - contactName - phone - street - complement - postalCode - city - country - countryCode - type additionalProperties: false - type: 'null' toAddress: anyOf: - type: object properties: name: anyOf: - type: string - type: 'null' contactName: anyOf: - type: string - type: 'null' phone: anyOf: - type: string - type: 'null' street: type: string complement: anyOf: - type: string - type: 'null' postalCode: type: string city: type: string country: anyOf: - type: string - type: 'null' countryCode: anyOf: - type: string - type: 'null' type: anyOf: - type: string enum: - HOME - WORK - type: 'null' required: - name - contactName - phone - street - complement - postalCode - city - country - countryCode - type additionalProperties: false - type: 'null' createBoxShipment: type: boolean parcel: anyOf: - type: object properties: weight: type: number length: type: number width: type: number height: type: number required: - weight - length - width - height additionalProperties: false - type: 'null' hasInsurance: type: boolean value: description: Declared value, in cents anyOf: - type: number - type: 'null' content: type: array items: type: object properties: id: anyOf: - type: string - type: 'null' name: type: string type: anyOf: - type: string - type: 'null' required: - id - name - type additionalProperties: false billingProfileId: anyOf: - type: string - type: 'null' notificationEmails: type: array items: type: string comment: anyOf: - type: string - type: 'null' shipmentId: description: The shipment created on execute, to read with `getShipment` anyOf: - type: string - type: 'null' required: - id - taskId - ticketId - offboardingId - executedAt - fromAddress - toAddress - createBoxShipment - parcel - hasInsurance - value - content - billingProfileId - notificationEmails - comment - shipmentId additionalProperties: false securitySchemes: apikey: scheme: bearer bearerFormat: API key type: http description: >- Use your Primo API key in the Authorization header as `Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.