> ## 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. # Update a return shipment intent > Fill or change the return shipment before it executes: addresses, parcel, declared value, content, billing profile. The value (in cents) and the billing profile start empty and must be set before `executeReturnShipmentIntent`; null leaves a field as it is, none can be emptied. 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`). Only the fields you send change. Refused with `INTENT_NOT_FOUND`, `INTENT_ALREADY_EXECUTED` once executed, `TICKET_CLOSED` when its task is completed or cancelled, `EXECUTION_IN_PROGRESS`, `BILLING_PROFILE_NOT_FOUND`. Key: WriteScope: Company ## OpenAPI ````yaml https://api.getprimo.com/openapi.json patch /return-shipment-intents/{intentId} 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/{intentId}: patch: tags: - Offboardings summary: Update a return shipment intent description: >- Fill or change the return shipment before it executes: addresses, parcel, declared value, content, billing profile. The value (in cents) and the billing profile start empty and must be set before `executeReturnShipmentIntent`; null leaves a field as it is, none can be emptied. 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`). Only the fields you send change. Refused with `INTENT_NOT_FOUND`, `INTENT_ALREADY_EXECUTED` once executed, `TICKET_CLOSED` when its task is completed or cancelled, `EXECUTION_IN_PROGRESS`, `BILLING_PROFILE_NOT_FOUND`. operationId: updateReturnShipmentIntent parameters: - name: intentId required: true in: path schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateReturnShipmentIntentBody' responses: default: description: '' content: application/json: schema: $ref: '#/components/schemas/ReturnShipmentIntent_Output' components: schemas: UpdateReturnShipmentIntentBody: 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' 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.