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

# Create or update a plan's order



## OpenAPI

````yaml /openapi.yaml put /agencies/{agencyId}/plans/{planId}/orders/{orderId}
openapi: 3.0.3
info:
  title: Kardinal ARO API
  version: 2.55.0
  description: This document specifies the REST API of Kardinal ARO v2.
  contact:
    url: https://kardinal.ai/
    email: contact@kardinal.ai
servers:
  - url: /api/v2
security:
  - access_token: []
tags:
  - name: Authenticate
    description: How to authenticate, and manage the access and refresh tokens.
  - name: Plan
    description: How to create, retrieve, update and delete plans.
  - name: Resource
    description: How to create, retrieve, update and delete resources in a plan.
  - name: Order
    description: How to create, retrieve, update and delete orders in a plan.
  - name: SimplePlan
    description: How to create a plan through the use of a simple plan.
paths:
  /agencies/{agencyId}/plans/{planId}/orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/agencyId'
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/orderId'
    put:
      tags:
        - Order
      summary: Create or update a plan's order
      operationId: putPlanOrder
      parameters:
        - $ref: '#/components/parameters/force'
      requestBody:
        description: The Order to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Order response updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedOrder'
        '201':
          description: Order response created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    agencyId:
      name: agencyId
      description: The agency id.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AgencyId'
    planId:
      name: planId
      description: The plan id.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RegexIdValidation'
    orderId:
      name: orderId
      description: The order id.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/RegexIdValidation'
    force:
      name: force
      description: >-
        If true, on an archived item, the requested action will be forced and
        the item will be unarchived.
      in: query
      schema:
        type: boolean
        default: false
  schemas:
    Order:
      type: object
      properties:
        id:
          description: Order ids must be unique within a plan.
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        properties:
          $ref: '#/components/schemas/Properties'
          description: >-
            Free-form key-value pairs (strings only) with no impact on
            optimization, such as a client reference. Returned unchanged in the
            plan and its solution.
        priority:
          description: 0 by default, can be negative.
          type: integer
          default: 0
        optional:
          type: boolean
          description: >-
            When true, this order is not mandatory: the algorithm may leave it
            unplanned without affecting the maximizeMandatoryStops objective,
            though it can still be scheduled via the maximizeOptionalStops
            objective. A shorthand for giving the order the lowest priority.
        requiredSkills:
          type: array
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - forklift
            - truck
        stops:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Stop'
          description: >-
            The ordered list of stops that make up this order. All stops of an
            order are planned onto the same resource, and their position in this
            array acts as a precedence constraint: the first stop must be
            visited before the second, and so on.
        successiveStops:
          type: boolean
          description: >-
            This constraint specifies that the stops within this order must be
            performed consecutively, without any intermediate stops from other
            orders. Useful when containers cannot be mixed, or to maintain a
            strict sequence of tasks. Mutually exclusive with maxStopSpan: only
            one of the two should be used.
        maxStopSpan:
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - id
        - stops
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    EnvelopedOrder:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/Order'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
        planVersion:
          $ref: '#/components/schemas/PlanVersion'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    AgencyId:
      description: The agency id.
      readOnly: true
      example: LND_Agency-42
      allOf:
        - $ref: '#/components/schemas/RegexPrefixedIdValidation'
    RegexIdValidation:
      type: string
      description: >-
        At least one character among those allowed: unaccented alpha-numeric
        characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".
      pattern: ^[a-zA-Z0-9-._~:@!$,]+$
    Properties:
      type: object
      additionalProperties:
        type: string
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Stop:
      oneOf:
        - $ref: '#/components/schemas/SingleStop'
        - $ref: '#/components/schemas/AlternativesStop'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Duration:
      type: string
      description: A period of time, expressed in the ISO8601 **duration** format.
      pattern: ^P(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
      example: PT4M
    PlanId:
      description: The plan id.
      readOnly: true
      example: plan-AB
      allOf:
        - $ref: '#/components/schemas/RegexIdValidation'
    PlanVersion:
      type: integer
      description: The plan version.
      readOnly: true
      minimum: 1
      example: 42
    EnvelopedErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    RegexPrefixedIdValidation:
      type: string
      description: An id beginning with a prefix and an underscore.
      pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$
    SingleStop:
      type: object
      properties:
        type:
          type: string
          enum:
            - single
          default: single
          description: >-
            Discriminator identifying this as a single stop, as opposed to an
            alternatives stop. Set this explicitly in every stop object you send
            rather than relying on the default — a typed client library
            re-validating this payload (for example by re-parsing it through its
            own discriminated-union models) generally needs the tag present in
            the data itself to pick the right stop variant, and rejects an
            object that omits it even though the field defaults on this schema.
        id:
          description: Single stop ids must be unique within a plan.
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        properties:
          $ref: '#/components/schemas/Properties'
          description: >-
            Free-form key-value pairs (strings only) with no impact on
            optimization. Returned unchanged in the solution.
        tags:
          description: prefix:suffix best practice, not forced.
          type: array
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - access:parking33
            - capa:bat22
            - setup:france
        position:
          allOf:
            - $ref: '#/components/schemas/Position'
          description: >-
            The geographic coordinates (latitude and longitude) of the stop.
            Addresses must be geocoded beforehand.
        kind:
          $ref: '#/components/schemas/StopKind'
          description: >-
            The type of operation performed at the stop (pickup, delivery, or
            acknowledgement), which determines how the stop's capacities affect
            the resource's load: added for a pickup, deducted for a delivery,
            and ignored for an acknowledgement (used to model interventions
            without cargo exchange).
        operationDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
        capacities:
          allOf:
            - $ref: '#/components/schemas/Capacities'
          description: >-
            The capacities consumed or released at this stop, as free-form
            key-value pairs. Must match at least one resource's capacities in
            the plan for the algorithm to assign this stop to an eligible
            resource.
        authorizedTimeWindows:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TaggedTimeWindow'
        preferredTimeWindows:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TaggedTimeWindow'
      required:
        - id
        - position
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    AlternativesStop:
      type: object
      description: A stop composed of different alternative single stops.
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        type:
          type: string
          enum:
            - alternatives
          description: >-
            Discriminator identifying this as an alternatives stop, as opposed
            to a single stop.
        alternatives:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/SingleStop'
          description: >-
            The list of single stops among which the algorithm must choose the
            best one to visit (for example choosing among multiple charging
            points or waste disposal sites). Using alternatives can increase
            optimization time.
      required:
        - type
        - alternatives
    Error:
      type: object
      readOnly: true
      properties:
        code:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        message:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        properties:
          $ref: '#/components/schemas/ErrorProperties'
      required:
        - message
        - code
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Position:
      type: object
      properties:
        lon:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude coordinate.
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude coordinate.
      required:
        - lon
        - lat
      example:
        lon: 2.3269331
        lat: 48.8812658
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    StopKind:
      type: string
      enum:
        - pickup
        - delivery
        - acknowledgement
      default: delivery
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Capacities:
      type: object
      additionalProperties:
        type: number
      example:
        volume: 9.5
        weight: 2200
        nbPackages: 23
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    TaggedTimeWindow:
      type: object
      description: TimeWindow with resource tags.
      properties:
        begin:
          $ref: '#/components/schemas/DateTime'
        end:
          $ref: '#/components/schemas/DateTime'
        resourceTags:
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - subcontractorA
            - subcontractorB
      required:
        - begin
        - end
    ErrorProperties:
      type: object
      additionalProperties:
        type: string
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    DateTime:
      type: string
      description: >-
        A full calendar date time, expressed in the ISO8601 **date** format:
        YYYY-MM-DDThh:mm:ssZ.
      example: '2019-11-15T12:34:56Z'
  responses:
    BadRequest:
      description: >-
        The server could not understand the request due to invalid content (bad
        syntax, bad format, bad values, etc).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    NotAuthenticated:
      description: The caller is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    Unauthorized:
      description: The caller is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    InternalServerError:
      description: An internal server error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
  securitySchemes:
    access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT

````