> ## Documentation Index > Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt > Use this file to discover all available pages before exploring further. # Record orders on a shipment > The response to the `ship-by-loop.purchase.requested` webhook. ### Required OAuth scope - `ship_by_loop:write` ## OpenAPI ````yaml post /ship-by-loop/shipments/{shipmentId}/orders openapi: 3.1.0 info: title: Ship by Loop - External Shipping Provider API version: 1.0.0 description: >- Endpoints an external shipping provider uses to fulfill shipments created within Ship by Loop. A provider calls these endpoints in response to the webhooks documented in [Ship by Loop shipment events](/webhook-reference/topics/ship-by-loop-shipment-webhook): 1. `POST /ship-by-loop/shipments/{shipmentId}/services` — add available service(s) to the shipment, in response to `ship-by-loop.services.requested`. 2. `POST /ship-by-loop/shipments/{shipmentId}/orders` — record order information for the services purchased, along with tracking and label details, in response to `ship-by-loop.purchase.requested`. 3. `POST /ship-by-loop/shipments/{shipmentId}/errors` — report one or more problems the provider could not resolve on its own (e.g. the carrier rejected an address, or a package can't be serviced). Call this any time such an error occurs — it isn't tied to a specific webhook trigger. servers: - url: https://api.loopreturns.com/api/{version} description: Production variables: version: default: latest description: >- `v2` is not a valid version segment — a request to `/api/v2/...` returns a 404. Use one of the values listed below instead. enum: - v1 - latest - 2026-07 - 2026-10 - unstable security: - oauth2: - ship_by_loop:write tags: - name: Ship by Loop paths: /ship-by-loop/shipments/{shipmentId}/orders: post: tags: - Ship by Loop summary: Record orders on a shipment description: |- The response to the `ship-by-loop.purchase.requested` webhook. ### Required OAuth scope - `ship_by_loop:write` operationId: recordShipmentOrders parameters: - $ref: '#/components/parameters/ShipmentId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordOrdersRequest' examples: withLabel: summary: Order with a printable label value: orders: - package_id: 2f0c48ef-1bdc-462e-ac36-8ad435b1b4cd external_id: ord_123 tracking_number: 1Z999 tracking_url: https://partner.example/track/1Z999 label_url: https://partner.example/labels/1.pdf qr_code_url: https://partner.example/qr/1.png labelless: summary: QR code only, no printable label description: >- At least one of `label_url` or `qr_code_url` is required — omitting both returns a 422 ("Package {package_id} must be assigned a QR Code or a Label"). This example provides only the QR code. value: orders: - package_id: 1d81b2ab-371b-4310-a023-c51ad643bd8f external_id: ord_123 tracking_number: 1Z999 tracking_url: null label_url: null qr_code_url: https://partner.example/qr/1.png responses: '204': $ref: '#/components/responses/NoContent' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ShipmentNotFound' '422': $ref: '#/components/responses/RecordOrdersUnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: parameters: ShipmentId: name: shipmentId in: path required: true description: The id of the Shipment schema: type: string examples: - ff8a4470-41e0-4cc3-9bfe-44564f4286b7 schemas: RecordOrdersRequest: type: object additionalProperties: false required: - orders properties: orders: type: array minItems: 1 items: $ref: '#/components/schemas/ExternalOrder' ExternalOrder: type: object additionalProperties: false required: - package_id - external_id - tracking_number properties: package_id: type: string examples: - 900a8671-35ad-4743-9b6c-2540d3bb1faf external_id: type: string maxLength: 64 description: The provider's identifier for the purchase order examples: - ord_123 tracking_number: type: string description: The tracking number for the package examples: - 1Z999 tracking_url: type: - string - 'null' format: uri description: The public tracking page for the package examples: - https://partner.example/track/1Z999 label_url: type: - string - 'null' format: uri description: The printable shipping label examples: - https://partner.example/labels/1.pdf qr_code_url: type: - string - 'null' format: uri description: The QR code examples: - https://partner.example/qr/1.png AuthError: type: object description: >- Returned when the access token or API key itself is missing, invalid, expired, or unrecognized. properties: error: type: object properties: code: type: string examples: - '401' http_code: type: string message: type: string examples: - Unauthorized. ScopeError: type: object description: >- Returned when the credentials are valid but lack the `ship_by_loop:write` scope for this endpoint. required: - errors properties: errors: type: string examples: - Unauthorized. ValidationError: type: object description: Request body failed validation. properties: message: type: string examples: - The services field is required errors: type: object additionalProperties: type: array items: type: string examples: - services: - The services field is required ShippingError: type: object properties: errors: type: array items: type: string examples: - >- Package 27edf77e-21f5-4ae7-8d4c-b32901d51226 does not belong to shipment faf035fd-9064-4b75-94a2-a6aeac7eac31 responses: NoContent: description: The request was processed successfully Unauthorized: description: >- The access token is missing, invalid, or expired, or it lacks the `ship_by_loop:write` scope. The response body differs depending on which of those is the case (see the two examples below). content: application/json: schema: oneOf: - $ref: '#/components/schemas/AuthError' - $ref: '#/components/schemas/ScopeError' examples: invalidCredentials: summary: Missing, invalid, or expired credentials value: error: code: '401' http_code: GEN-UNAUTHORIZED message: Unauthorized. missingScope: summary: Valid credentials, missing the required scope value: errors: Unauthorized. Forbidden: description: >- The caller is not permitted to modify this shipment. The response body is empty. ShipmentNotFound: description: No shipment matches `shipmentId`. The response body is empty. RecordOrdersUnprocessableEntity: description: The request could not be processed content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/ShippingError' examples: validationFailure: summary: Payload failed validation value: errors: orders: - The orders field is required domainFailure: summary: Business rule violation value: errors: - >- Package a25cc361-6d65-4f8b-a78b-15b0657bc35a does not belong to shipment 7cdfc082-6dc7-4e9d-8f77-c4250b9cd573 missingLabelOrQrCode: summary: Neither a label nor a QR code was provided value: errors: - >- Package a25cc361-6d65-4f8b-a78b-15b0657bc35a must be assigned a QR Code or a Label InternalServerError: description: An error occurred. The response body is empty. securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://oauth.loopreturns.com/authorize tokenUrl: https://oauth.loopreturns.com/oauth/token scopes: ship_by_loop:write: Submit services, orders, and errors for Ship by Loop shipments ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.