Dassault Systèmes orders API

openapi: 3.2.0
info:
  title: Dassault Systèmes Partners accreditations Orders API
  description: APIs exposed by Dassault Systèmes to its partners and resellers.
  version: 0.10.0
  license:
    name: Dassault Systèmes 2025
    url: https://www.3ds.com/
  x-logo:
    url: https://www.3ds.com/assets/3ds-navigation/3DS_corporate-logo_blue.svg
    altText: Dassault Systèmes
    backgroundColor: '#FFFFFF'
servers:
- url: https://apigw-prd.3ds.com
  description: Main (production) server
- url: https://apigw-ppt.3ds.com
  description: Server for development by Partners (Non Production)
- url: https://apigw-qal.3ds.com
  description: Server for Quality Assurance Testing (Non Production)
- url: https://apigw-ptd.3ds.com
  description: Server for preprod validation (Non Production)
- url: https://apigw-ppd.3ds.com
  description: Server for postprod validation (Non Production)
security:
- ApiKeyAuth: []
tags:
- name: orders
  description: 'This section defines the operations related to orders, including the creation, management, and fulfillment of orders.


    It provides a comprehensive overview of the order lifecycle, from initial request to final delivery.


    The operations in this section are designed to support the efficient and effective management of orders, ensuring that customers receive their products or services in a timely and satisfactory manner.


    The following operations are included in this section:


    * Searching Orders

    * Getting Order Details

    '
paths:
  /order/api4partners/v0/orders/search:
    post:
      summary: Search Orders using various filters
      description: 'Searches for orders based on various filter criteria such as creation date, booking date, last modified date, and more.

        Supports pagination through `skip` and `top` query parameters.

        '
      tags:
      - orders
      operationId: searchOrders
      parameters:
      - name: skip
        in: query
        description: "The number of records to skip in the result set.  \nUse this for paginating through results. Defaults to 0 if not specified.\nFor example, `skip=20` will skip the first 20 records.\n"
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: top
        in: query
        description: "The maximum number of records to return in the response.  \nUse this to limit the size of the result set. Defaults to 10 if not specified.\nFor example, `top=10` will return up to 10 records starting from the position defined by `skip`.\n"
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      requestBody:
        description: "A JSON object specifying filter criteria for retrieving matching orders.\n\nThe request must include at least one of the following sub-objects: \n- `creationDateTime`\n- `bookingDateTime`\n- `lastUpdateDateTime`\n- `installedBaseNumber`\n- `onlineInstanceSeatId`\n- `billToPoReferences`\n\nThese will be combined using an AND operator if more than one is provided.\n"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orders_search_req'
            examples:
              basicSearchSingleCriteria:
                summary: Sample request body for searching orders using a single criterion
                description: 'This example demonstrates how to search for orders using the `creationDateTime` criterion.

                  If the `to` value is not provided under `creationDateTime`, it is implicitly set to either 7 days after the `from` timestamp or the current time—whichever is earlier.


                  This JSON payload retrieves all orders created between `01-April-2025 1:30 AM UTC` and `08-April-2025 1:30 AM UTC`.

                  '
                value:
                  creationDateTime:
                    from: '2025-04-01T01:30:00Z'
              advancedSearchMultipleCriteria:
                summary: Sample request body for searching orders using multiple criteria
                description: 'This example demonstrates how to search for orders using multiple criteria:

                  - `creationDateTime`

                  - `lastUpdateDateTime`

                  - `installedBaseNumber`

                  - `transactionType`


                  If the `to` value is not provided under `creationDateTime`, it is implicitly set to either 7 days after the `from` timestamp or the current time—whichever is earlier.


                  If the `from` value is not provided under `lastUpdateDateTime`, it is implicitly set to 3 days before the `to` timestamp.


                  This JSON payload searches for all `Renewal Orders` that:

                  - Were created between `01-April-2025 1:30 AM UTC` and `08-April-2025 1:30 AM UTC`

                  - Were modified between `22-May-2025 7:45 PM UTC` and `25-May-2025 7:45 PM UTC`

                  - Have the InstalledBase Number `LN00001234567`

                  '
                value:
                  creationDateTime:
                    from: '2025-04-01T01:30:00Z'
                  lastUpdateDateTime:
                    to: '2025-05-25T19:45:00Z'
                  installedBaseNumber: LN00001234567
                  transactionType: RN
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_post_orders_search'
              examples:
                successful_ordersSearch_OneResult:
                  summary: Sample successful basic Search for orders
                  description: Sample successful basic search for orders with only 1 result.
                  value:
                    data:
                    - transaction:
                        id: PO_A123456789
                        type: PO
                        status: Sent to DSx.Finance
                        description: XYZ Company Order 50 products
                      creationDateTime: '2024-05-21T14:30:00Z'
                      dsRecievedPoDate: '2024-05-21'
                      bookingDateTime: '2024-05-29T18:00:00Z'
                      currency: USD
                      onlineConsentStatus: Not Applicable
                      billToSalesRepresentative: DOE, Jane
                      billToPoReference: EXAMPLE-CORP-20250518
                      billToSite:
                        id: '100012345678901'
                        name: Example Corporation
                        localName: 示例公司
                        locationId: 1
                      soldToSite:
                        id: '200012345678901'
                        name: Foobar Inc
                        localName: फ़ूबार इंक
                        locationId: 2
                      businessUnit:
                        id: BU001
                        name: Corporate Sales Unit A
                        localTimezone: CET
                    info:
                      success: true
                      statusCode: 200
                      estimatedSearchCount: 1
                200_ordersSearch_No-Result:
                  summary: Sample successful Search for orders without any results
                  description: Sample successful Search for orders without any results
                  value:
                    data: []
                    info:
                      success: true
                      statusCode: 200
                      estimatedSearchCount: 0
        '400':
          description: Bad request, invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_post_orders_search'
              examples:
                failedOrderSearch_BadRequest:
                  summary: Example response for a bad request
                  description: 'This example shows the response returned when a bad request is made, such as when no search criteria are provided.

                    '
                  value:
                    data: []
                    info:
                      success: false
                      statusCode: 400
                      estimatedSearchCount: 0
                    error:
                    - type: errors:3dx:invalidRequest
                      title: Missing required search criteria
                      errors:
                      - detail: 'Please specify at least one search criterion. Valid options include: `creationDateTime`, `bookingDateTime`, `lastUpdateDateTime`, `installedBaseNumber`, `onlineInstanceSeatId`, `billToPoReferences`.'
                        pointer: '#'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_basic_unauthorized'
              examples:
                401_missing-apikey:
                  summary: Service response in case of missing APIKEY.
                  description: Basic Service response in case of missing APIKEY in request
                  value:
                    message: Missing API key in request
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403_basic_forbidden'
              examples:
                403_forbidden:
                  summary: Access Forbidden
                  description: Access Forbidden. Typical reason could be usage of invalid API-KEY or a valid one but for a scope on which access has not been granted by 3DS.
                  value:
                    message: API Consumer Not allowed
        '429':
          description: Too many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429_too_many_requests'
              examples:
                429_too_many_requests:
                  summary: Too many Requests
                  description: The service cannot handle the request as too many have been received.
                  value:
                    message: Too many requests, please try again later
  /order/api4partners/v0/orders/{id}:
    get:
      summary: Get Order details
      description: Retrieves all the details of an order given its Dassault Systèmes reference.
      tags:
      - orders
      operationId: getOrderDetails
      parameters:
      - name: id
        in: path
        required: true
        description: id of the order to get details from
        schema:
          type: string
          example: PO_000123456789
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_get_orders'
              examples:
                successful_getOrderDetails:
                  summary: Sample successful response for order details query
                  description: Example of response for order details with line and subLine
                  value:
                    data:
                    - transaction:
                        id: PO_A123456789
                        type: PO
                        status: Sent to DSx.Finance
                        description: XYZ Company Order 50 products
                      businessUnit:
                        id: BU001
                        name: Corporate Sales Unit A
                        localTimezone: CET
                      billToSite:
                        id: '100012345678901'
                        name: Example Corporation
                        localName: 示例公司
                        locationId: 1
                      billToContact: DOE, Jini
                      soldToSite:
                        id: '200012345678901'
                        name: Foobar Inc
                        localName: फ़ूबार इंक
                        locationId: 2
                      creationDateTime: '2024-05-21T14:30:00Z'
                      dsReceivedPoDate: '2024-05-21'
                      bookingDateTime: '2024-05-29T18:00:00Z'
                      currency: USD
                      onlineConsentStatus: Not Applicable
                      billToSalesRepresentative: DOE, Jane
                      billToPoReference: EXAMPLE-CORP-20250518
                      agreement:
                        type: General VAR Agreement
                        reference: Enterprise License Agreement Q2 2024
                      sboNumber: ABC0012345
                      customerRequestedArrivalDate: '2025-05-31'
                      dsSalesRepresentative: DOE, John
                      isMultiYear: false
                      hasExitClause: false
                      recurringChargeBillingCycle: Calendar Year
                      opportunity: A1B2-C3D4E5
                      paymentTerms: Net Date of Invoice + 60 days
                      licenseChargeConditions:
                      - sequenceNumber: 1
                        lineGroup: SBL0001234567
                        onlineInstanceSeatId: R1122334455667
                        orderType: Stop - Transform
                        usageScope: GEO EMEA
                        promotion:
                          id: PAO0000111
                          name: 3DEXPERIENCE for small and medium business
                          combination: Collaborative Design & Engineering Learning @Home
                        waiver:
                          endDate: '2025-09-15'
                        licenseChargeBreakdown:
                        - sequenceNumber: 1
                          installedBaseNumber: LN00012345678
                          subOrderType: New License
                          revenueType: ALC
                          portfolio: CATIA
                          release: 3DEXPERIENCE R2025x
                          product:
                            trigram: ABC
                            type: Named User
                            number: 1AB-ABC
                            name: Generic Product Standard with Cloud Services
                            dsOffering: Licensed Program
                          quantity: 2
                          unitListPrice: 1000
                          totalListPrice: 2000
                          billToNetAmount: 1930
                          billToAnnualAmount: 1930
                          billToDiscountPercentage: 30.5
                          billToMarginPercentage: 10.5
                          maximumCustomerNetAmount: 1958.95
                          maximumCustomerAnnualAmount: 1958.95
                          minimumCustomerDiscountPercentage: 10.5
                          startDate: '2025-06-01'
                          endDate: '2026-05-31'
                          duration: 2
                          calculatedStartDate: '2025-06-01'
                          calculatedEndDate: '2026-05-31'
                          yearNumber: 1
                          coupon:
                            name: 10% off on Installation Fee
                            discountPercentage: 10
                          inflation:
                            date: '2025-07-01'
                            ratio: 1.04
                            exception: Capping To Price List
                    info:
                      success: true
                      statusCode: 200
                      estimatedSearchCount: 1
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/4xx_get_orders'
              examples:
                failedOrderGet_BadRequest:
                  summary: Example response for missing required parameter
                  description: 'This example shows the response returned when transaction id is missing in the request.

                    '
                  value:
                    data: []
                    info:
                      success: false
                      statusCode: 400
                      estimatedSearchCount: 0
                    error:
                    - type: errors:3dx:invalidRequest
                      title: Bad Request
                      errors:
                      - detail: A required parameter is missing.
                        pointer: '#/transactionId'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_basic_unauthorized'
              examples:
                401_missing-apikey:
                  summary: Service response in case of missing APIKEY.
                  description: Basic Service response in case of missing APIKEY in request
                  value:
                    message: Missing API key in request
        '403':
          description: Unauthorized, missing or invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403_basic_forbidden'
              examples:
                403_forbidden:
                  summary: Access Forbidden
                  description: Access Forbidden. Typical reason could be usage of invalid API-KEY or a valid one but for a scope on which access has not been granted by 3DS.
                  value:
                    message: API Consumer Not allowed
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/4xx_get_orders'
              examples:
                failedOrderGet_BadRequest:
                  summary: Example response for a Resource not Found
                  description: 'This example shows the response returned when no Order exists with the provided Id.

                    '
                  value:
                    data: []
                    info:
                      success: false
                      statusCode: 400
                      estimatedSearchCount: 0
                    error:
                    - type: errors:3dx:resourceNotFound
                      title: Not found
                      errors:
                      - detail: Change your parameters to get results
                        pointer: '#'
        '429':
          description: Too many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429_too_many_requests'
              examples:
                429_too_many_requests:
                  summary: Too many Requests
                  description: The service cannot handle the request as too many have been received.
                  value:
                    message: Too many requests, please try again later
components:
  schemas:
    creation_datetime:
      type: string
      description: 'UTC timestamp when the order was created in the system.


        Format: ISO 8601 UTC (e.g., `2025-05-21T14:30:00Z`)

        '
      format: date-time
      example: '2025-05-21T14:30:00Z'
    recurring_charge_billing_cycle:
      type: string
      description: 'Identifies how often invoices are sent for ALC and ASC licenses. In the event of prorating (to an anniversary date, in the first month, or in the first quarter) or cancellation and refund or overpayment, the prorate calculation is based on 30 day months.

        '
      enum:
      - Calendar Month
      - Calendar Quarter
      - Calendar Semester
      - Calendar Year
      - Full At Date
      - Immediate
      - Rolling Month 360
      - Rolling Quarter 360
      - Rolling Semester 360
      - Rolling Year 360
      x-enumDescriptions:
        Calendar Month: bill recurring license charges through the end of the current calendar month and for full month periods thereafter (or until indicated anniversary date if earlier)
        Calendar Quarter: bill recurring license charges through the end of the current calendar quarter and for full 3 month periods thereafter (or until indicated anniversary date if earlier)
        Calendar Semester: bill recurring license charges through the end of the current semester and for full 6 month periods thereafter (or until indicated anniversary date if earlier)
        Calendar Year: bill recurring license charges through the end of the current calendar year and for full 12 month periods thereafter (or until indicated anniversary date if earlier)
        Full At Date: bill recurring license charges for a 12-month period (or until indicated anniversary date if earlier) taking into consideration any start dates contained in the PO. If multiple durations (in contrast to quantity) of a recurrent license charge are ordered, they are invoiced at up front rather than on an annual basis. For example, if a PO is for two years of ALC, the two years are invoiced upfront at the start date rather than year one following order completion and year two the next year.
        Immediate: bill is generated by DS at the PO approval date for the full amount of the order not taking into consideration any license start dates contained in the PO. For example, if a PO is for two years of ALC, the two years are invoiced upfront at PO approval date.
        Rolling Month 360: bill recurring license charges from the start date through start date plus one month duration (or until indicated end date if earlier).
        Rolling Quarter 360: bill recurring license charges from the start date through start date plus 3 months duration (or until indicated end date if earlier).
        Rolling Semester 360: bill recurring license charges from the start date through start date plus 6 months duration (or until indicated end date if earlier).
        Rolling Year 360: bill recurring license charges from the start date through start date plus 12 months (or until indicated end date if earlier). For example, if PO is for 2 years of ALC with a start date February 1st, the 2 invoicing periods will be from February 1st to January 31st.
      example: Calendar Year
    200_get_orders:
      type: object
      description: Response body returned upon a successful order details request.
      properties:
        data:
          $ref: '#/components/schemas/order_get_data'
        info:
          $ref: '#/components/schemas/info'
        error:
          $ref: '#/components/schemas/error'
      required:
      - data
      - info
    transaction:
      type: object
      description: Transactional details of the order.
      properties:
        id:
          type: string
          description: Unique identifier of the order. Can represent a Purchase Order or a Renewal Notification.
          maxLength: 13
          example: PO_A123456789
        type:
          $ref: '#/components/schemas/transaction_type'
        status:
          $ref: '#/components/schemas/order_processing_status'
        description:
          type: string
          description: Short description given to the Purchase Order / Renewal Notification.
          maxLength: 30
          example: XYZ Company Order 50 products
    date_time_from:
      type: string
      description: 'This property represents a timestamp in UTC format, following the ISO 8601 standard.

        All date-time values must be provided in Coordinated Universal Time (UTC).

        The timestamp must not be set in the future.

        If not provided, the system will automatically calculate it by subtracting the maximum number of days specified for the time range defined for the parent search criteria.

        '
      format: date-time
      example: '2024-05-21T14:30:00Z'
    order_revenue_type:
      type: string
      enum:
      - ALC
      - ASC
      - ELC
      - PLC
      - PSC
      - QLC
      - QSC
      - SLC
      - SSC
      - TBL2
      - TBL3
      - TSC2
      - TSC3
      - TSC5
      - ULC
      - USC
      - XLC
      - XSC
      - YLC
      - YSC
      x-enumDescriptions:
        ALC: Annual License Charge
        ASC: Annual Service Charge
        ELC: Evaluation Licence Charge
        PLC: Primary License Charge
        PSC: Primary Service Charge
        QLC: Quarter License Charge
        QSC: Quarter Service Charge
        SLC: Service/support license charge
        SSC: Service Charge
        TBL2: Term Based Licenses 2
        TBL3: Term Based Licenses 3
        TSC2: Term Service Charge 2
        TSC3: Term Service Charge 3
        TSC5: Term Service Charge 5
        ULC: Administration license charge
        USC: Upfront Service Charge
        XLC: X License Charge
        XSC: eXtended Service Charge
        YLC: Yearly License Charge
        YSC: Yearly Service Charge
      example: ALC
    online_consent_status:
      type: string
      description: 'Status of the online consent request sent to the designated contact.

        '
      enum:
      - Accepted
      - Expired
      - Not Applicable
      - Not Requested
      - Refused
      - Requested
      x-enumDescriptions:
        Accepted: The online consent request has been successfully accepted by the designated contact.
        Expired: The online consent request has expired and is no longer valid.
        Not Applicable: The online consent request is not applicable to the current situation or context.
        Not Requested: The online consent request has not been sent to the designated contact.
        Refused: The online consent request has been refused by the designated contact.
        Requested: The online consent request has been sent to the designated contact, but the status is pending.
      default: ''
      example: Accepted
    legal_entity:
      type: object
      properties:
        id:
          type: string
          description: 'A unique identifier for the company. The value will be within the Legal Entity Family.

            '
          maxLength: 15
          example: '100012345678901'
        name:
          type: string
          description: 'The registered name of the company in English.

            '
          maxLength: 120
          example: Example Corporation
        localName:
          type: string
          description: 'The registered name of the company in the local language.

            '
          maxLength: 120
          example: 示例公司
        locationId:
          type: integer
          description: "A unique identifier representing the company's location. \nMust be an integer between 1 and 999.\n"
          minimum: 1
          maximum: 999
          example: 2
      required:
      - id
      - name
      - locationId
    order_get_data:
      type: array
      description: List of orders retrieved during the search operation.
      items:
        type: object
        description: Summary information for a single order.
        properties:
          transaction:
            $ref: '#/components/schemas/transaction'
          businessUnit:
            $ref: '#/components/schemas/business_unit'
          billToSite:
            type: object
            description: Legal entity to which Dassault Systèmes will issue the invoice (Bill To).
            $ref: '#/components/schemas/legal_entity'
          soldToSite:
            type: object
            description: Legal entity of the company that is the Final Customer of Dassault Systèmes products (Sold To).
            $ref: '#/components/schemas/legal_entity'
          agreement:
            type: object
            description: 'Contains details about the license agreement associated with the licenses being ordered in the Purchase Order (PO).

              '
            properties:
              type:
                type: string
                description: 'Type or classification of the agreement.

                  '
                maxLength: 100
                example: General VAR Agreement
              reference:
                type: string
                description: 'A short, descriptive title or label assigned to the agreement at the time of its creation.

                  This helps users identify the specific agreement applied to the order.

                  It can be selected in the Purchase Order only for agreement types where the sub-group is `Instantiated`.

                  '
                maxLength: 254
                example: Enterprise License Agreement Q2 2024
            required:
            - type
          billToContact:
            type: string
            description: Full name of the contact person at the Bill To site (billing entity) who is responsible for the order. This contact person is the primary point of communication for billing-related inquiries and transactions. Format-`LASTNAME, Firstname` (e.g., `DOE, John`).
          creationDateTime:
            $ref: '#/components/schemas/creation_datetime'
          dsReceivedPoDate:
            $ref: '#/components/schemas/ds_received_po_date'
          bookingDateTime:
            $ref: '#/components/schemas/booking_datetime'
          currency:
            $ref: '#/components/schemas/currency'
          onlineConsentStatus:
            $ref: '#/components/schemas/online_consent_status'
          billToSalesRepresentative:
            $ref: '#/components/schemas/billto_sales_representative'
          billToPoReference:
            $ref: '#/components/schemas/billto_po_reference'
          sboNumber:
            type: string
            description: 'Unique identifier of the Special Bid Offer (SBO) that served as the basis for creating the order.

              Typically used to track and reference special pricing or offer conditions.

              '
            maxLength: 10
            example: ABC0012345
          customerRequestedArrivalDate:
            type: string
            description: 'Customer Requested Arrival Date (CRAD) indicates the date by which the Final Customer requests delivery of the DS Licenses and Support Order.


              > **Note:** CRAD is a non-binding request. While DS will make reasonable efforts to meet this date, it does not constitute a contractual commitment.


              - Orders can still receive ''Finance Approved'' status, media can be ''Shipped'', and license keys can be issued and marked as ''Completed'' irrespective of the CRAD.

              - The **Support Start Date** in the Installed Base will never begin before the CRAD.

              - Format: ISO 8601 format (YYYY-MM-DD)

              - License keys will remain inactive until the Support Start Date.

              '
            format: date
            example: '2025-05-31'
          dsSalesRepresentative:
            type: string
            description: 'Full name of the Dassault Systèmes (DS) sales representative responsible for the order.


              Format: `LASTNAME, Firstname` (e.g., `DOE, John`)

              '
            example: DOE, John
          isMultiYear:
            type: boolean
            description: 'Indicates whether the order is part of a Multi-Year deal (i.e., duration longer than one year),

              applicable for revenue types such as `YxC` or `AxC`.

              '
            example: true
          hasExitClause:
            type: boolean
            description: 'Indicates whether the agreement includes an exit clause requiring the Final Customer to pay early termination fees

              if they end the rental before the completion of the multi-year engagement.

              '
            example: true
          recurringChargeBillingCycle:
            $ref: '#/components/schemas/recurring_charge_billing_cycle'
          opportunity:
            type: string
            description: 'Unique identifier for the sales opportunity as recorded in the **My Sales Pipeline** system.

              This value helps link the order to its originating sales activity.

              '
            example: A1B2-C3D4E5
          paymentTerms:
            type: string
            description: 'Payment terms for the order, as provided by the Finance Department.

              Specifies the agreed period within which the payment must be made.

              '
            maxLength: 50
            example: Net Date of Invoice + 60 days
          licenseChargeConditions:
            type: array
            description: 'A list of conditions that determine when the license is charged for the order.

              These conditions specify the circumstances under which the license fee is applied, such as:


              - The number of users or seats that are licensed.

              - The type 

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dassault/refs/heads/main/openapi/dassault-orders-api-openapi.yml