> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an order to ship

> Address, items with shipped quantities, shipments, returns and notes.

**Permission:** `fulfillment:read`



## OpenAPI

````yaml /api-reference/openapi/user-api.yaml get /orders/{invoiceId}
openapi: 3.0.3
info:
  title: PapelShip Store API
  version: 1.0.0
  description: >-
    Manage your PapelShip store from your own systems: create orders, sync
    products and stock, ship physical orders, answer support tickets and react
    to events.


    Every request needs your API key in `x-api-key` and your store ID in
    `x-store-hash`. Amounts are integers in minor units (`2999` = 29.99). Dates
    are ISO 8601 in UTC.
  contact:
    name: PapelShip Support
    email: support@papelship.com
    url: https://papelship.com
servers:
  - url: https://app.papelship.com/api/v1
    description: Production
security:
  - ApiKey: []
    StoreHash: []
tags:
  - name: Account
    description: Your key, store and payment methods.
  - name: Orders
    description: Create orders, take manual payments, cancel, refund and read deliveries.
  - name: Products
    description: Products and their settings.
  - name: Variants & stock
    description: Variants, physical stock and license keys.
  - name: Product content
    description: Media, SEO, payment methods, files and stock alerts.
  - name: Categories
    description: Organise products.
  - name: Groups
    description: Collections of products.
  - name: Coupons
    description: Discount codes.
  - name: Customers
    description: Buyers and their history.
  - name: Blocklist
    description: Emails and IPs that can't place orders.
  - name: Reviews
    description: Customer reviews.
  - name: Support
    description: Support tickets.
  - name: Subscriptions
    description: Recurring products and auto-renewals.
  - name: Fulfillment
    description: Ship physical orders.
  - name: Returns
    description: Return requests.
  - name: Shipping settings
    description: Zones, rates and locations.
  - name: Webhooks
    description: Endpoints, deliveries and event types.
  - name: Affiliates
    description: Partner programme.
  - name: Analytics
    description: Sales summary.
paths:
  /orders/{invoiceId}:
    get:
      tags:
        - Fulfillment
      summary: Get an order to ship
      description: |-
        Address, items with shipped quantities, shipments, returns and notes.

        **Permission:** `fulfillment:read`
      operationId: getPhysicalOrder
      parameters:
        - in: path
          name: invoiceId
          required: true
          schema:
            type: string
            example: c35ffd-19a1b2c3d4e-8c7a20
          description: Public order ID.
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  order:
                    $ref: '#/components/schemas/PhysicalOrder'
                required:
                  - success
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PhysicalOrder:
      type: object
      properties:
        id:
          type: string
          description: Public order ID.
          example: c35ffd-19a1b2c3d4e-8c7a20
        status:
          type: string
        fulfillment_status:
          type: string
          enum:
            - unfulfilled
            - partially_fulfilled
            - fulfilled
            - delivered
            - returned
            - cancelled
        paid_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        customer_email:
          type: string
        currency:
          type: string
        total_cents:
          type: integer
        shipping_cents:
          type: integer
        shipping_method:
          type: object
          properties: {}
          additionalProperties: true
          nullable: true
        shipping_address:
          allOf:
            - type: object
              properties:
                full_name:
                  type: string
                  example: Alex Morgan
                company:
                  type: string
                  nullable: true
                phone:
                  type: string
                  nullable: true
                  example: +44 20 7946 0958
                email:
                  type: string
                  nullable: true
                country_code:
                  type: string
                  description: ISO 3166-1 alpha-2.
                  example: GB
                region:
                  type: string
                  description: State, province or county.
                  nullable: true
                  example: Greater London
                city:
                  type: string
                  nullable: true
                  example: London
                district:
                  type: string
                  nullable: true
                line1:
                  type: string
                  example: 221B Baker Street
                line2:
                  type: string
                  nullable: true
                postal_code:
                  type: string
                  nullable: true
                  example: NW1 6XE
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: Use as `invoice_item_id`.
              product_id:
                type: integer
              variant_id:
                type: integer
                nullable: true
              name:
                type: string
              variant_name:
                type: string
                nullable: true
              sku:
                type: string
                nullable: true
              quantity:
                type: integer
              total_cents:
                type: integer
              ships:
                type: boolean
              shipped_quantity:
                type: integer
        shipments:
          type: array
          items:
            $ref: '#/components/schemas/Shipment'
        returns:
          type: array
          items:
            $ref: '#/components/schemas/Return'
        notes:
          type: array
          items:
            $ref: '#/components/schemas/OrderNote'
    Shipment:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          enum:
            - label_created
            - shipped
            - in_transit
            - out_for_delivery
            - delivered
            - failed_attempt
            - returned_to_sender
            - cancelled
        carrier_code:
          type: string
          example: dhl_express
        carrier_name:
          type: string
          example: DHL Express
        tracking_number:
          type: string
          nullable: true
        tracking_url:
          type: string
          nullable: true
        shipped_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
        delivered_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
        notify_customer:
          type: boolean
        items:
          type: array
          items:
            type: object
            properties:
              invoice_item_id:
                type: integer
              qty:
                type: integer
        events:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentEvent'
    Return:
      type: object
      properties:
        id:
          type: string
          example: 9f1c2a7b3d4e5f60
        object:
          type: string
          example: return
        order_id:
          type: string
        status:
          type: string
          enum:
            - requested
            - approved
            - rejected
            - in_transit
            - received
            - refunded
            - closed
            - cancelled
        reason:
          type: string
          enum:
            - damaged
            - wrong_item
            - not_as_described
            - size_fit
            - changed_mind
            - missing_parts
            - other
        customer_note:
          type: string
          nullable: true
        merchant_note:
          type: string
          nullable: true
        return_location_id:
          type: integer
          nullable: true
        return_carrier_code:
          type: string
          nullable: true
        return_carrier_name:
          type: string
          nullable: true
        return_tracking_number:
          type: string
          nullable: true
        return_tracking_url:
          type: string
          nullable: true
        restocked:
          type: boolean
        refund_cents:
          type: integer
          nullable: true
        items:
          type: array
          items:
            type: object
            properties:
              invoice_item_id:
                type: integer
              quantity:
                type: integer
              product_name:
                type: string
              variant_name:
                type: string
                nullable: true
        events:
          type: array
          description: Per-order reads only.
          items:
            type: object
            properties:
              status:
                type: string
              note:
                type: string
                nullable: true
              actor:
                type: string
              created_at:
                type: string
                format: date-time
                example: '2026-10-04T12:00:00.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        resolved_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-10-04T12:00:00.000Z'
    OrderNote:
      type: object
      properties:
        id:
          type: integer
        body:
          type: string
        created_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code. Branch on this, not on the message.
          example: VALIDATION_FAILED
        error:
          type: string
          description: Human-readable message.
          example: customer_email must be a valid email address
        details:
          type: object
          properties: {}
          description: Extra context, for example `field` for validation errors.
          additionalProperties: true
        request_id:
          type: string
          description: Include this when you contact support.
          example: req_7YbK2mQ9xP1cRt4v
      required:
        - success
        - code
        - error
    ShipmentEvent:
      type: object
      properties:
        status:
          type: string
          enum:
            - label_created
            - shipped
            - in_transit
            - out_for_delivery
            - delivered
            - failed_attempt
            - returned_to_sender
            - cancelled
        location:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        occurred_at:
          type: string
          format: date-time
          example: '2026-10-04T12:00:00.000Z'
        source:
          type: string
          example: merchant
  responses:
    Unauthorized:
      description: >-
        Missing, invalid or expired API key.


        Codes: `MISSING_API_KEY`, `MISSING_STORE_HASH`, `INVALID_API_KEY`,
        `API_KEY_EXPIRED`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: INVALID_API_KEY
            error: Invalid API Key
            request_id: req_7YbK2mQ9xP1cRt4v
    Forbidden:
      description: >-
        The key is not allowed to do this.


        Codes: `INSUFFICIENT_SCOPE`, `IP_NOT_ALLOWED`, `STORE_NOT_ALLOWED`,
        `STORE_API_NOT_IN_PLAN`, `FEATURE_NOT_ENABLED`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: INSUFFICIENT_SCOPE
            error: This API key needs the orders:write permission
            request_id: req_7YbK2mQ9xP1cRt4v
    NotFound:
      description: |-
        The record does not exist in this store.

        Codes: `NOT_FOUND`, `STORE_NOT_FOUND`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: NOT_FOUND
            error: Invoice not found
            request_id: req_7YbK2mQ9xP1cRt4v
    RateLimited:
      description: >-
        Too many requests. Wait `Retry-After` seconds.


        Codes: `RATE_LIMITED` (300 requests per minute per key),
        `STORE_API_MONTHLY_QUOTA_EXCEEDED` (your plan's monthly quota).
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: RATE_LIMITED
            error: Too many requests. The limit is 300 requests per minute per key.
            request_id: req_7YbK2mQ9xP1cRt4v
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Store API key (`pk_live_...`). Create it in **Developers › API
        keys**.
    StoreHash:
      type: apiKey
      in: header
      name: x-store-hash
      description: >-
        The ID of the store the request is for. Shown in **Developers › API
        keys**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.