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

# Admin Update Order Status

> Admin: update order status, optionally add tracking info and a history comment.

VEN-6: ``refunded`` on an order whose money is still held (payment
``paid`` / ``partially_refunded``) runs the real refund of the remaining
amount first (same path as POST /refunds: gateway or manual record). It used
to change the label only and email "refunded" with the whole total while
nothing went back. The "refunded" email carries the amount actually
refunded and is never sent when nothing was refunded.

VEN-6 (follow-up): ``refunded`` on an order never collected (payment
``pending``/``failed``) is a 409 ``order.refund_not_collected``: nothing can
go back, and «Cancelled» is the status of an order that was never paid.

VEN-13: the timeline row of the new status is visible to the customer, who
reads the status in the language of the shop; the operator's comment goes
with it only with ``comment_public`` (default: a staff-only note).
VEN-28: ``notify_customer`` is recorded only when an email was queued, and
the response carries the timeline with the new rows.

ORD-3: an order in the trash → 409 ``order.trashed``; the answer is
`StaffOrderOut`.

ORD-4: ``cancelled`` runs `lifecycle.apply_cancel_effects` (the trash's
too): the gateway attempt of every unpaid online order is voided, the
units that were really taken go back (`stock_taken`), and the
``order.cancelled`` webhook fires.



## OpenAPI

````yaml https://api.vellaro.io/openapi/admin.json patch /api/v1/admin/orders/{order_id}
openapi: 3.1.0
info:
  title: Vellaro Admin API
  description: >-
    Store management under `/api/v1/admin`, for back ends and integrations.
    Every call takes `Authorization: Bearer <token>`: an admin API token or a
    staff user's token. The permissions of its role decide what it can do,
    always in its own store.
  version: 0.1.0
servers:
  - url: https://api.vellaro.io
    description: Produzione
security: []
tags:
  - name: Orders
    description: >-
      Orders and manual orders, payments, refunds, shipments, invoices, returns,
      customer subscriptions.
  - name: Products
    description: Products, variants, images, prices and discounts, product lookups.
  - name: Categories & catalog setup
    description: >-
      Categories, brands, attributes, options, filters, downloadable files,
      recurring profiles.
  - name: Inventory
    description: Stock of the variants and stock statuses.
  - name: Customers
    description: Customers, customer groups, custom fields.
  - name: Reviews & questions
    description: Moderation of product reviews and questions.
  - name: Promotions & coupons
    description: Coupons and gift vouchers.
  - name: Marketing
    description: Campaigns, newsletter subscribers, affiliates and their commissions.
  - name: Content
    description: >-
      CMS pages, menus, banners, information pages, flipbooks, media library,
      SEO URLs, email templates, translations.
  - name: Settings
    description: >-
      Store settings, email delivery, languages, currencies, physical stores,
      social login providers.
  - name: Shipping
    description: Couriers, shipping rates, weight and length classes.
  - name: Taxes & geo
    description: Tax classes, rates and rules; countries, zones and geo zones.
  - name: Integrations & modules
    description: >-
      Integrations, plugins and modules (Iute, extra warranty, Nextera, Financa
      5, WhatsApp, Firebase), outbound webhooks.
  - name: AI
    description: AI content generation and the settings of the AI shopping assistant.
  - name: Imports
    description: 'CSV imports and the universal import: runs, mappings, previews, undo.'
  - name: Reports & dashboard
    description: Dashboard figures and reports.
  - name: Users & API keys
    description: Staff users and roles, publishable keys, admin API tokens.
  - name: Audit
    description: The store's audit log.
paths:
  /api/v1/admin/orders/{order_id}:
    patch:
      tags:
        - Orders
      summary: Admin Update Order Status
      description: >-
        Admin: update order status, optionally add tracking info and a history
        comment.


        VEN-6: ``refunded`` on an order whose money is still held (payment

        ``paid`` / ``partially_refunded``) runs the real refund of the remaining

        amount first (same path as POST /refunds: gateway or manual record). It
        used

        to change the label only and email "refunded" with the whole total while

        nothing went back. The "refunded" email carries the amount actually

        refunded and is never sent when nothing was refunded.


        VEN-6 (follow-up): ``refunded`` on an order never collected (payment

        ``pending``/``failed``) is a 409 ``order.refund_not_collected``: nothing
        can

        go back, and «Cancelled» is the status of an order that was never paid.


        VEN-13: the timeline row of the new status is visible to the customer,
        who

        reads the status in the language of the shop; the operator's comment
        goes

        with it only with ``comment_public`` (default: a staff-only note).

        VEN-28: ``notify_customer`` is recorded only when an email was queued,
        and

        the response carries the timeline with the new rows.


        ORD-3: an order in the trash → 409 ``order.trashed``; the answer is

        `StaffOrderOut`.


        ORD-4: ``cancelled`` runs `lifecycle.apply_cancel_effects` (the trash's

        too): the gateway attempt of every unpaid online order is voided, the

        units that were really taken go back (`stock_taken`), and the

        ``order.cancelled`` webhook fires.
      operationId: admin_update_order_status_api_v1_admin_orders__order_id__patch
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Order Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatusUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_StaffOrderOut_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    OrderStatusUpdate:
      properties:
        status:
          type: string
          title: Status
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        comment_public:
          type: boolean
          title: Comment Public
          default: false
        notify_customer:
          type: boolean
          title: Notify Customer
          default: false
        tracking_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Tracking Number
        shipping_carrier:
          anyOf:
            - type: string
            - type: 'null'
          title: Shipping Carrier
      type: object
      required:
        - status
      title: OrderStatusUpdate
      description: 'Admin endpoint: manually set order status.'
    ApiResponse_StaffOrderOut_:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/StaffOrderOut'
            - type: 'null'
        meta:
          anyOf:
            - $ref: '#/components/schemas/PaginationMeta'
            - type: 'null'
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      title: ApiResponse[StaffOrderOut]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StaffOrderOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: User Id
        status:
          type: string
          title: Status
        payment_status:
          type: string
          title: Payment Status
        payment_method:
          type: string
          title: Payment Method
        stripe_payment_intent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Stripe Payment Intent Id
        subtotal:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Subtotal
        shipping_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Shipping Cost
        tax:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Tax
        tax_rate:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Tax Rate
        prices_include_tax:
          type: boolean
          title: Prices Include Tax
          default: false
        discount_amount:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Discount Amount
        total:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Total
        amount_refunded:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount Refunded
          default: '0'
        currency:
          type: string
          title: Currency
        coupon_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Coupon Code
        customer_email:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Email
        customer_phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Phone
        shipping_address:
          additionalProperties: true
          type: object
          title: Shipping Address
        billing_address:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Billing Address
        tracking_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Tracking Number
        shipping_carrier:
          anyOf:
            - type: string
            - type: 'null'
          title: Shipping Carrier
        invoice_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Invoice Number
        invoice_issued_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Invoice Issued At
        customer_vat_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Vat Id
        customer_tax_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Tax Code
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        items:
          items:
            $ref: '#/components/schemas/StaffOrderItemOut'
          type: array
          title: Items
          default: []
        history:
          items:
            $ref: '#/components/schemas/OrderHistoryOut'
          type: array
          title: History
          default: []
        payment_attempt:
          anyOf:
            - $ref: '#/components/schemas/PaymentAttemptOut'
            - type: 'null'
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        channel:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel
        created_by_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By Name
        email_customer:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Email Customer
        delivery_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Delivery Mode
        manual_discount:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Manual Discount
        fiscal_external:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Fiscal External
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deleted At
        deleted_by_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Deleted By Name
        delete_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Delete Reason
        delete_reason_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Delete Reason Code
        purge_after:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Purge After
        imported:
          type: boolean
          title: Imported
          default: false
        deletion:
          anyOf:
            - $ref: '#/components/schemas/OrderDeletionSummary'
            - type: 'null'
      type: object
      required:
        - id
        - user_id
        - status
        - payment_status
        - payment_method
        - stripe_payment_intent_id
        - subtotal
        - shipping_cost
        - tax
        - discount_amount
        - total
        - currency
        - coupon_code
        - customer_email
        - customer_phone
        - shipping_address
        - billing_address
        - tracking_number
        - shipping_carrier
        - invoice_number
        - notes
        - created_at
        - updated_at
      title: StaffOrderOut
    PaginationMeta:
      properties:
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total:
          type: integer
          title: Total
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
        - page
        - page_size
        - total
        - total_pages
      title: PaginationMeta
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StaffOrderItemOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        variant_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Variant Id
        product_name:
          type: string
          title: Product Name
        variant_sku:
          type: string
          title: Variant Sku
        variant_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variant Attributes
        quantity:
          type: integer
          title: Quantity
        unit_price:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Unit Price
        total_price:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Total Price
        kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Kind
        parent_item_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parent Item Id
        service_meta:
          anyOf:
            - $ref: '#/components/schemas/StaffOrderItemServiceOut'
            - type: 'null'
        catalog_unit_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Catalog Unit Price
        price_override_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Price Override Reason
      type: object
      required:
        - id
        - variant_id
        - product_name
        - variant_sku
        - variant_attributes
        - quantity
        - unit_price
        - total_price
      title: StaffOrderItemOut
    OrderHistoryOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        event_type:
          type: string
          title: Event Type
          default: status_change
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Comment
        notify_customer:
          type: boolean
          title: Notify Customer
        actor_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Actor Name
        is_internal:
          type: boolean
          title: Is Internal
          default: false
        meta:
          additionalProperties: true
          type: object
          title: Meta
          default: {}
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - comment
        - notify_customer
        - created_at
      title: OrderHistoryOut
    PaymentAttemptOut:
      properties:
        method:
          type: string
          const: iute
          title: Method
          default: iute
        state:
          anyOf:
            - type: string
              enum:
                - awaiting
                - approved
                - declined
            - type: 'null'
          title: State
      type: object
      title: PaymentAttemptOut
      description: >-
        Il sottoinsieme pubblico del tentativo corrente di un ordine Iute
        (§7.1).


        `state`: `awaiting` (domanda inviata, anche con un importo da
        verificare),

        `approved` (approvata, firmata o pagata: il pagato si legge da

        `payment_status`), `declined`, null (nessuna domanda vista: sessione
        aperta,

        chiusa senza domanda, scaduta o superata). Lo scrive

        `iute.storefront.public_attempts`; al posto dell'oggetto c'è null per un

        altro metodo e per un ordine Iute importato senza tentativi.
    OrderDeletionSummary:
      properties:
        deletable:
          type: boolean
          title: Deletable
        blockers:
          items:
            type: string
          type: array
          title: Blockers
          default: []
      type: object
      required:
        - deletable
      title: OrderDeletionSummary
      description: Il riassunto del controllo nel dettaglio dello staff (`StaffOrderOut`).
    StaffOrderItemServiceOut:
      properties:
        years:
          anyOf:
            - type: integer
            - type: 'null'
          title: Years
        base_unit_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Base Unit Price
        percent:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Percent
        min_price:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Min Price
        rounding:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rounding
        version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Version
        terms_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Path
      type: object
      title: StaffOrderItemServiceOut
      description: >-
        La fotografia completa della garanzia extra per lo staff (GAR-15, D10):
        la regola com'era all'ordine.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

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