Partner Web Services Placeorder V2 Service Manual

Partner Web Services

PlaceOrder v2 Service Manual

Version 2.0.54

Contents

1 Introduction ...... 10 1.1 Overview ...... 10 1.2 Supporting Resources ...... 10 2 Service Overview ...... 11 2.1 Subscription to Autodesk ...... 11 2.1.1 Renewable Order Model ...... 11 2.1.2 Maintenance to Subscription (M2S) ...... 12 2.1.3 Positive Extension End-Date ...... 12 2.1.4 Multi-User trade in ...... 13 2.1.5 Deal Discount Approval ...... 14 2.1.6 Premium Initial Orders ...... 15 2.1.7 Premium Renewals and True-up ...... 15 2.1.8 Cloud Credits purchase ...... 16 2.1.9 NFR (Not for Resale) purchase ...... 16 3 Service Endpoints ...... 17 4 Pilot Run and Go Live ...... 18 5 Request/Response Schema ...... 19 5.1 Request ...... 19 5.1.1 High-Level Entity Relationship model ...... 19 5.1.2 Low-Level Entity Relationship model ...... 20 5.1.3 Detailed Request JSON Structure ...... 21 5.2 Response ...... 37 5.2.1 High-Level Entity Relationship model ...... 37 5.2.2 Detailed Response JSON Structure ...... 38 6 Sample Requests/Responses ...... 39

AUTODESK PlaceOrder v2 Service Reference Manual 2

6.1 Initial Order ...... 39 6.2 Additions – Add seats ...... 41 6.3 Additions – Add products ...... 42 6.4 Renewals ...... 44 6.5 Premium Renewals and True-ups ...... 45 6.6 Positive extension ...... 47 6.7 Maintenance-to-Subscription switch ...... 48 6.8 Multi-User trade in ...... 50 7 Formatting standards ...... 53 8 Error Messages ...... 53 8.1 System Error codes ...... 53 8.2 Service Error Codes ...... 54 8.3 Asynchronous Error Codes ...... 61 Appendix A: Pro-Rating logic ...... 61 Appendix B: Contract Extension policies (DRAFT) ...... 61 Appendix C: Multi-user Trade-in ...... 62 Timelines ...... 62 Transition ...... 62 Multi-user trade-in eligibility ...... 64 Products not eligible for the multi-user trade-in offer ...... 64 Appendix D: Premium Renewals and True-up use cases ...... 65 True-up scenario with one Primary Admin and one Team: ...... 65 True-up scenario with one Primary Admin and multiple Teams ...... 66 True-up scenario with multiple Primary Admins ...... 67 True-up scenario with multiple True-ups corresponding to multiple Primary Admins ... 69 True-down scenario with one Primary Admin and one Team: ...... 71

AUTODESK PlaceOrder v2 Service Reference Manual 3

Tables

Table 1: Contract extension example ...... 13 Table 2: Service endpoints ...... 17 Table 3: Detailed JSON Request Structure for Initial Orders (Renewal) ...... 23 Table 4: Detailed JSON Request Structure for Additions to existing Orders (Renewal) ..... 26 Table 5: Detailed JSON Request Structure for Renew Orders ...... 29 Table 6: Detailed JSON Request Structure for M2S Orders ...... 31 Table 7: Detailed JSON Request Structure for Multi-User Trade-in Orders ...... 34 Table 8: Account JSON Model ...... 35 Table 9: Contact JSON Model ...... 36 Table 10: Detailed JSON Response Structure ...... 38 Table 11: Authentication Error Codes ...... 54 Table 12: Application Error Codes ...... 60 Table 13: Pro-Rating Logic ...... 61

Figures

Figure 1: Contract extension example ...... 13 Figure 2: Request High-Level JSON Schema Model ...... 19 Figure 3: Request Low-Level Entity Model ...... 20 Figure 4: Response High-Level JSON Schema Model ...... 37 Figure 5: before & after the Multi-user Trade-in ...... 63 Figure 6: Trade-in calendar ...... 63

AUTODESK PlaceOrder v2 Service Reference Manual 4

Revision History

Version Date Author Comments 2.0.0 Jan 17, 2017 Abdullah Sahin • Initial version of PlaceOrder API v2 2.0.1 Mar 16, 2017 Jordi Gilabert • Updated the Low-Level entity relationship Model in 5.1.2 • Changed transaction_id description in 5.2.2 2.0.2 Mar 17, 2017 Jordi Gilabert • Removed Multi-Event examples • Full document re-formatting • Fixed all cross-references 2.0.4 Jun 30, 2017 Oscar Lopez • Removed Software coordinator section from payload 2.0.5 Jul 20, 2017 Jordi Gilabert • Error codes updated in Section 8 2.0.6 Jul 25, 2017 Jordi Gilabert • Request Payloads updated 2.0.7 Aug 02, 2017 Shantnu Jain • Changed ‘serialNumber’ to ‘subscriptionReferenceNumber’ • Changed ‘subscriptionId’ to ‘partnerSubscriptionId’ 2.0.8 Aug 03, 2017 Jordi Gilabert • Minor format changes 2.0.9 Aug 18, 2017 Jordi Gilabert • Updated links to DEVPortal documentation and API Authentication Guide, from QA to STG environment • Updated low level entity relationship diagram 2.0.10 Aug 22, 2017 Jordi Gilabert • Fixed structure for ShipTo from Contact to Account 2.0.11 Aug 31, 2017 Jordi Gilabert • API Name format fixed 2.0.12 Oct 03, 2017 Oscar Lopez • Removed all QA references 2.0.13 Oct 24, 2017 Jordi Gilabert • Emphasize that Contract Manager information is only needed for existing contracts if has to be updated 2.0.14 Nov 29, 2017 Jordi Gilabert • Country code max length set 2 characters to align with ISO code max length.

AUTODESK PlaceOrder v2 Service Reference Manual 5

2.0.15 Apr 3, 2018 Jordi Gilabert • Added M2S support • Fixed cosmetic errors 2.0.16 May 22,2018 Shantnu Jain & • Removed field Jordi Gilabert switchToContractNumber from section 5.1.3.4 • Added section 8.3 to refer to GetOrderStatus Reference manual 2.0.17 July 30, 2018 Jordi Gilabert • Added support for multiple additions in the same request in Section 0 2.0.18 August 14, Jordi Gilabert • Updated M2S request fields’ order 2018 for a better readability on section 5.1.3.4 • Updated valid contract term options for M2S on section 5.1.3.4 2.0.19 Sept 18, 2018 Jordi Gilabert • Changed OpportunityNumber field in Table 5. OpportunityNumber is Mandatory when performing Renews. 2.0.20 Oct 16, 2018 Jordi Gilabert • Partner Subscription ID field behavior changed for initial and add product orders. 2.0.21 Nov 11, 2018 Jordi Gilabert • Removed Add Seats SKU references 2.0.22 Nov 14, 2018 Jordi Glabert • partnerSubscriptionId definition update 2.0.23 Jan 8, 2019 Denny Bulcao • Grammar Review 2.0.24 Jan 16, 2019 Jordi Gilabert • Added Pro-Rating schema for Additions. 2.0.25 Feb 27, 2019 Jordi Gilabert • Added 3-days grace period functionality 2.0.26 Mar 22, 2019 Jordi Gilabert • Removed 35-chars limit for End- Customer and Ship-To names 2.0.27 Apr 23, 2019 Jordi Gilabert • Changed “email” field length from 35 to 80 in Table 9 2.0.28 July 22, 2019 Jordi Gilabert • Added error 41013 (request timeout) in section 8.1

AUTODESK PlaceOrder v2 Service Reference Manual 6

2.0.29 Aug 20, 2019 Jordi Gilabert • It is clarified that contractStartDate allows a maximum future date of 30 days including the order date and not a natural month (section 5.1.3.1). 2.0.30 Sep 4, 2019 Jordi Gilabert • New functionality: Phone Number support during order booking: o Table 8 (Account) updated with the new field “phoneNumber” • New functionality: Positive Extension End Date: o Functionality explained in section 2.1.3 o “contractEndDate” added in Table 5 o “opportunityNumber” is not required when “contractEndDate” is populated (Table 5) o Added section 6.6 with sample request/response o Error 43076 added in section 8.2 • Document re-formatted for an improved reading. 2.0.31 Oct 31, 2019 Jordi Gilabert • Changes to specify that during contract extensions, new contract end date has to be sent and opportunity number must not be send (sections 2.1.3 and 0) 2.0.32 Nov 14, 2019 Jordi Gilabert • New Future Start Date for Add Product functionality has been included in Table 4. New related error codes 43014, 43083 and 43085 added to Table 12.

AUTODESK PlaceOrder v2 Service Reference Manual 7

• contractStartDate allows a maximum future date of 31 days including the order date instead of 30 (section 5.1.3.1). 2.0.33 Nov 26, 2019 Jordi Gilabert • Contract extension functionality description improved in section 2.1.3 2.0.34 Nov 27, 2019 Jordi Gilabert • Contract extension date limits updated and functional example provided in section 2.1.3 2.0.35 Dec 17, 2019 Jordi Gilabert • First and Last names char restrictions added on section 5.1.3.7 • Contract Extension cannot be combined with 3-days grace period (section 5.1.3.3) • Appendix B: Contract Extension policies (DRAFT) has been included with the policies applicable for Contract Extensions. 2.0.36 Jan 21, 2020 Jordi Gilabert • New Multi-User trade in functionality has been included in Sections 2.1.4 and 5.1.3.5. Sample payload added in Section 6.8 2.0.37 Feb 18, 2020 Jordi Gilabert • New Appendix C: Multi-user Trade- in 2.0.38 Mar 4, 2020 Jordi Gilabert • Fixed action name for Multi-user trade-in in section 5.1.3.5 2.0.39 Mar 27, 2020 Jordi Gilabert • Specified that a maximum of 23 lineitems per part number are allowed to Trade-in in Table 7 2.0.40 Apr 27, 2020 Jordi Gilabert • Fixed sample request for MU Trade- in in section 6.8 2.0.41 May 5, 2020 Jordi Gilabert • Fixed partNumber field description in section 5.1.3.5 for more clarity 2.0.42 Jun 8, 2020 Jordi Gilabert • Fixed Multi-User Trade-in sample request in section 6.8

AUTODESK PlaceOrder v2 Service Reference Manual 8

2.0.43 Jun 22, 2020 Jordi Gilabert • Added government entity support in section 5.1.3.1 2.0.44 Oct 30, 2020 Jordi Gilabert • New functionality: Deal Discount support in sections 5.1.3.1, 5.1.3.2 and 5.1.3.3 2.0.45 Dec 1, 2020 Jordi Gilabert • Address validation specified in section 5.1.3.6 2.0.46 Jan 11, 2020 Jordi Gilabert • New functionality: Premium Initial Order in section 2.1.6 2.0.47 Mar 19, 2020 Jordi Gilabert • New error codes 43114, 43115, 43116 and 43117 in Table 12 2.0.48 Apr 7, 2020 Jordi Gilabert • New error codes 43063, 43105 and 43118 in Table 12 2.0.49 Apr 26, 2020 Jordi Gilabert • Fixed government entity support in section 5.1.3.1 2.0.50 May 14, 2021 Jordi Gilabert • Included 3 days grace period pricing for MU Trade-in transactions in section 5.1.3.5 2.0.51 Jun 9, 2021 Jordi Gilabert • Add Cloud Credits related error codes in Table 12 (43120, 43122, 43124, 43125 and 43126) 2.0.52 Jun 10, 2021 Jordi Gilabert • Added support for Cloud Credits (section 2.1.8) and NFR (section 2.1.9) 2.0.53 Jun 21, 2021 Jordi Gilabert • Added Flex related error codes in Table 12 (43127) 2.0.54 Aug 30, 2021 Jordi Gilabert • Added Premium Renewals and True-up support in section 2.1.7 and Appendix D: Premium Renewals and True-up use cases

AUTODESK PlaceOrder v2 Service Reference Manual 9

1 Introduction

1.1 Overview

Autodesk Partner Web Services is an automation solution for order placement directly from its partners to Autodesk, all with low-touch from partners and zero-touch from Autodesk. This new business capability enables true B2B web service transactions between partners and Autodesk.

For partners to effectively implement Autodesk web services, partner developers should be familiar with REST web services, OAuth, and JSON.

1.2 Supporting Resources

Autodesk Partner Developer Portal: The Autodesk Partner Developer Portal offers a place for partner developers to build and test their own applications by subscribing to Autodesk web services and helps partners get connected with Autodesk. The Partner Developer Portal features a robust repository of service documentation, provides an ongoing conduit to the services to support partner teams, and features a community to allow partner developers to share insights and information. A partner administrator can invite and keep track of all the developers associated with the account and all the details of the applications they submit. Developers can then explore the information related to a service, understand the way the service works, and test the service to see how it works with their applications. For more information, please visit the Partner Developer Center.

Authentication API Documentation: This documentation guides partners through the process of generating credentials, signatures, and access tokens necessary to utilize service APIs. It also covers the development of a partner’s integrating application. It provides basic information on web service integration and demonstrates the development of a typical application. For more information, please check the latest version of the API Authentication Guide.

AUTODESK PlaceOrder v2 Service Reference Manual 10

2 Service Overview

PlaceOrder Service exposes API resources for managing orders: /orders/fulfillment. Version 1 of this service is intended to be used to manage Recurring (Auto-Renew) contracts. Version 2 handles order creation and managing Renewable orders. With this API, partners can create and specify events to add seats and products to existing active agreements or renew those that are expiring.

This document includes various scenarios of the PlaceOrder v2 service that are eligible for order generation or agreement modification within the Autodesk environment. The details of the services included in the order fulfillment process are below:

• Submitting new renewable orders • Adding seats to existing renewable agreements • Adding products to existing renewable agreements • Renewing an existing contract • Switching from a Maintenance contract to a Subscription contract • Extending a contract end date • Switching from a Multi-User to a Single-User agreement

When an Order Fulfillment request has been made, the API service performs basic validations for schema, SKUs, contracts, and pricing details to ensure the data is valid to fulfill the order request. If the validations are successful, the order is queued for further processing and a response is returned, indicating that the order is being processed. The response contains a unique transaction ID as a reference to the order. Partners can query the status of their order by using Get Order Status service or, alternatively, by SMS service which they can subscribe to for order process notifications.

2.1 Subscription to Autodesk

Subscription to Autodesk is a pay-as-you-go approach, with the options of annual or multi- year terms given to customers. PlaceOrder Version 2 provides API access to the Renewable Model only.

2.1.1 Renewable Order Model

When customers subscribe to a service under the renewable order model, the subscription is active for the term selected in their subscription (annual or multi-year). The subscription

AUTODESK PlaceOrder v2 Service Reference Manual 11 can be renewed 90 days prior to the end of the term through the renew event in the Order Fulfillment API.

2.1.2 Maintenance to Subscription (M2S)

Maintenance to Subscription (M2S) is a special offer designed to help customers on a maintenance plan move to a subscription.

• Maintenance plan: Autodesk Offering that is attached to a Perpetual License and offers updates, upgrades and other select benefits. • Subscription plan: Autodesk Offering that allows a customer access to product(s), service(s), upgrades, and/or support for a specified term.

2.1.3 Positive Extension End-Date

This functionality allows the customers to extend their service contract to a specified end date, so that all their contracts and subscriptions are aligned to the same end date.

Goals:

• Provide the customer more flexibility to extend their current contract term outside of renewal. • Simplify the renewal process for the end customer, reseller, and distributor by aligning all contracts to end in the same renewal window. • Extend all end customer’s contracts to one end date to allow the customer to merge their contracts into one or switch all of their subscriptions to a new offering with one common renewal date. Functionality:

• This functionality is achieved using the Renewal action in PlaceOrder v2 API. • When specifying a new end date, a renewal opportunity must not be sent. • Positive extension proration rules need to be applied. GetMyPrice API automatically calculates the prorated price for positive extensions. • All active subscriptions on a contract must be extended. • Multi-user subscriptions with extra territory rights cannot be extended. • For positive extension renewal the contract end date needs to be after the current contract end date and fall within a specific range as defined in the Agreement validation below:

AUTODESK PlaceOrder v2 Service Reference Manual 12

o A customer can extend a contract to a new end date up to 4 years from today's (order) date. o A customer can extend a contract to a new end date up to 1094 days in the future from their current contract end date.

Contract Start Date End Date Maximum Extension Maximum Term extension Order date extension date by date by contract order date Annual 1/1/2019 31/12/2019 29/12/2022 10/9/2019 10/9/2023 2-Years 1/1/2019 31/12/2020 30/12/2023 5/7/2019 5/7/2023 3-Years 1/1/2019 31/12/2021 29/12/2024 21/8/2020 21/8/2024 Table 1: Contract extension example

Figure 1: Contract extension example

(*) note: Please check Appendix B: Contract Extension policies (DRAFT) for additional information.

2.1.4 Multi-User trade in

This offering will help a Multi-User (Network) subscription to be traded in for Single User licenses of the same product. This function can be used to trade in M2S Multi-User subscriptions with assets created by Maintenance to Subscription (M2S), standard-priced Multi-User subscriptions and it can be used as a single hop from a Maintenance Multi-User to a Single User subscription.

AUTODESK PlaceOrder v2 Service Reference Manual 13

For a limited time, at renewal, customers will be able to trade in 1 Multi-User subscription or 1 Multi-User Maintenance seat for 2 Single User Subscription seats. Here are some examples:

• An M2S Multi-User seat from Switch Years 1 to 3 can be traded in for two M2S Single User seats each at half the price of the current M2S Multi-User price for Switch Year 1 to 3. • An M2S Multi-User seats from Switch Year 4 switch can be traded in for two M2S Single User seats each at half the price of the current M2S Multi-User price for Switch Year 4 • A Full Price Multi-User seat can be traded in for two Single-User seats at half price of the full price Multi-User subscription. • Maintenance customers can also trade in a network/maintenance multi-user seat and receive two M2S Single-User subscription seats for half the price of an M2S Multi-User seat. Further details regarding timing and conditions will be communicated separately and documented in Autodesk policies which may override details provided in this document. NOTE: During the trade in period if a customer does not choose to take the 2 for 1 trade in offer at their next renewal, they may lose the ability to get 2 single user subscriptions for the price of 1 and may only get a 1 for 1 trade in on any subsequent renewals.

(*) note: Please check Appendix C: Multi-user Trade-in for additional information.

2.1.5 Deal Discount Approval

When a DDA opportunity exists, Partners can take advantage of the Price discount. To do this, apart from sending the DDA opportunity ID, Partner will need to calculate and send the appropriate discounted VAD price, as GetMyPrice API will not do this calculation.

Example:

• Regular SRP (what end-customer pays) price is 1000 • Regular VAD (what the Distributor pays to Autodesk) price is 800 • DDA sets a 10% discount • End customer will pay 900 (1000 – 10%) • VAD needs to send 720 (800 – 10%) in the request

AUTODESK PlaceOrder v2 Service Reference Manual 14

When a DDA order request is detected, price validations are relaxed at API Service level and the order is blocked until a Sales representative reviews and releases it. Order status can be queried using GetOrderStatus API as usual. Please note that PWS does not admit Deal Discount Approvals for already discounted programs like M2S or Multi-User Trade-in.

2.1.6 Premium Initial Orders

Partners can submit Premium subscriptions along with regular subscriptions as part of Initial Order flow. To do so, corresponding Premium materials SKUs has to be sent in the payload (These SKUs can be identified with as their Product Line is PREMSUB).

If at least one of the subscriptions is premium, the order will be flagged to be blocked waiting for a Sales representative to review and release it. Using GetOrderStatus Partners will know which is the current status and when the order has been released.

Please note that is possible to combine DDA and Premium functionalities and the same order.

2.1.7 Premium Renewals and True-up

PWS supports Premium Subscription ordering and renewals for both Annual and Multi- Year subscriptions:

• Annual Premium Subscription initial orders • Multi-Year Premium Subscription initial orders • Renewals and True-up (both Annual and Multi-Year terms) • Multi-Year anniversary True-up

Partners can rely on GetOpportunity API to retrieve the True-up information.

“Renewal” action will be used for the PlaceOrderV2 transaction, while in Line Items, each True-up will be included in separated Items indicating the Line Action “True-up”.

Please check Appendix D: Premium Renewals and True-up use cases for examples

AUTODESK PlaceOrder v2 Service Reference Manual 15

2.1.8 Cloud Credits purchase

Partners can buy Cloud Credits via PWS considering the following statements:

• Can be purchased only with a valid existing/new subscription, using order actions Initial, Add-on or Renewal • Can NOT be purchased as part of a Maintenance to Subscription or Multi-User Trade-in transaction • Cloud Credit dates are not tightly coupled with the contract referred to. The contract end dates, and cloud credit validity end dates can be different • No pro-ration is applicable to Cloud Credits • Add seat scenario is NOT supported • Deal Discount Approvals are supported • Cloud Credits are valid for one year from the start date. Will not be usable if the related contract/subscription is not valid anymore • Cloud Credits can have a future start date

2.1.9 NFR (Not for Resale) purchase

PWS provides the ability for Partners to purchase an NFR products for partners and training centers to use for demo purposes. NFR will be driven by SKU characteristics, so no API modification is needed from a standard product ordering.

Please note that NFR (Term License or Cloud Credits) are not allowed on Commercial Subscriptions (neither on Initial nor Additions orders)

AUTODESK PlaceOrder v2 Service Reference Manual 16

3 Service Endpoints

Environment URL Staging https://enterprise-api- stg.autodesk.com/v2/orders/fulfillment Production https://enterprise- api.autodesk.com/v2/orders/fulfillment Table 2: Service endpoints

AUTODESK PlaceOrder v2 Service Reference Manual 17

4 Pilot Run and Go Live

Please note that the following features will not be available during the pilot run. (Partners can still use these fields in their requests, but their values will be ignored by Autodesk APIs.)

• Media Kit • Fee SKUs/ETR • Cross Country Orders • VPA/CQS • Volume Purchase Order • Promo Code • Partner Line Item ID

Additionally, the service is only able to manage one-single event per request for a given contract (i.e. one Initial Order OR one/various Addition for the same contract OR one contract Renewal OR one M2S switch):

• Initial Order o Create a new order with one/multiple products with one/multiple seats • Additions o Add seats to one existing line of a contract o Create a new line in an existing contract o Add seats to different lines within the same contract o Add seats to an existing line and create a new line within the same contract o Any combination of the above (i.e. Add seats to 3 different lines and create 2 new lines) • Renewal o Renew one single contract o Contract extension • Maintenance to Subscription o Switch one Maintenance contract to a Subscription contract • Multi-User trade in o Switch from a Multi-User contract to a Single-User contract

AUTODESK PlaceOrder v2 Service Reference Manual 18

5 Request/Response Schema

5.1 Request

5.1.1 High-Level Entity Relationship model

The following figure represents the high-level request schema of the PlaceOrderV2 service. For a detailed description of each item, please refer to section 5.1.3.

Figure 2: Request High-Level JSON Schema Model

AUTODESK PlaceOrder v2 Service Reference Manual 19

5.1.2 Low-Level Entity Relationship model

Figure 3: Request Low-Level Entity Model

AUTODESK PlaceOrder v2 Service Reference Manual 20

5.1.3 Detailed Request JSON Structure

The following tables explain the schema for the Request of the API service. For a better reading, the payloads are split based on the operation requested.

• Initial Renewable Order • Additions to an existing Renewable Order • Renew a Renewable Order • Maintenance to Subscription switch * Please note that Bold elements denote Groups. Plain elements denote Input Fields.

5.1.3.1 Initial Order

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h action M Action to be performed by the service. String - Free Text 35 “Initial” Other possible For Initial orders its value has to be “Initial” values for action are – “Initial”, “Add-On” and “Renewal” endCustomer { M Default End Customer information for the JSON Object - - order placed. account {} M Default End Customer Account information for JSON Object - - the order placed. Please refer to Table 8 (Account) for entity details. contractManager {} M Default Contract Manager for the order JSON Object - - placed.

AUTODESK PlaceOrder v2 Service Reference Manual 21

Please refer to Table 9 (Contact) for entity details. } - - - - - shipTo {} M Default Ship to Account for the order placed. JSON Object - -

Please refer to Table 8 (Account) for entity details. reseller { M Default Reseller Account for the order placed. JSON Object - - csn M Reseller CSN. String - Free Text 35 5930928324 } - - - - - soldTo { M Default Sold To Account for the order placed. JSON Object - - csn M The value should always be equal to the String - Free Text 35 5986958493 renewable CSN of the partner calling the API. } - - - - - governmentEntity { O End Customer’s associated government entity JSON Object - - so that the proper split is assigned for revenue allocation. csn M End Customer’s associated government entity String - Free Text 35 0070171212 CSN } - - - - - poNumber M Partner Purchase Order number. String - Free Text 35 PO_201602394833 43 customerPoNumber O Customer Purchase Order number. String - Free Text 35 PO_2016023942419 7 contractStartDate O Requested contract start date. String - Date ISO 10 2016-01-22 8601 format This value can only be in the future and not longer than 31 days including the order date. priceDate O Explicit price date to support the 3 days grace String - Date ISO 10 2016-01-20 period functionality 8601 format lineItems [ M List of product to be ordered. Array - JSON - - Object { 1..N One occurrence per product. JSON Object - -

AUTODESK PlaceOrder v2 Service Reference Manual 22

partNumber M Initial Order SKU for renewable subscription. String - Free Text 18 128I1-WW3492- T000 partnerSubscriptionId O Fresh value generated by the service caller. String - Free Text 40 42e0e7d0-e7d7- Formerly known as subscription Id. 408a-8471- bb2acc62fbc2 • The subscription ID is alpha-numeric. • The subscription ID can contain a hyphen. • The subscription ID can contain a space. • The subscription ID does NOT need to be in UUID v4 format. quantity M Number of seats. Number - Integer - 3 netPrice M Price for the line item. Please note that String - Free Text 20 330.42 quantity is a factor for the pricing.

Ex – If a customer has ordered 3 seats of a product and each seat is $110.14 then netPrice = 3*$110.14 = $330.42 } - - - - ] - - - - orderDiscounts [ O List of Discounts to be applied. Array - JSON - - Object { 1..N One occurrence per discount. JSON Object - - discountId M Discount ID for approved Deal Discounts String - Free Text 15 A-3755776 (Opportunity number associated with the Deal Discount Number) discountType M Type of discount being applied. Valid values: String - Free Text 20 DDA

• DDA } - - - - ] - - - - Table 3: Detailed JSON Request Structure for Initial Orders (Renewal)

AUTODESK PlaceOrder v2 Service Reference Manual 23

5.1.3.2 Additions

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h action M Action to be performed by the service. String - Free Text 35 “Add-On”

For additions its value has to be “Add-On” endCustomer { O Default End Customer information for the JSON Object - - order placed. contractManager {} O Default Contract Manager for the order JSON Object - - placed. Please refer to Table 9 (Contact) for entity details. } - - - - - shipTo {} M Default Ship to Account for the order placed. JSON Object - -

AUTODESK PlaceOrder v2 Service Reference Manual 24

product to which the additional seats will be added. contractStartDate O Date to add a product with a future start date. String - Date ISO 10 2016-01-22 8601 format NOT Supported for adding seats.

This value can only be in the future and not longer than 31 days including the order date. It cannot exceed the current service contract’s end date. priceDate O Explicit price date to support the 3 days grace String - Date ISO 10 2016-01-20 period functionality 8601 format lineItems [ M List of products to be added or modified. Array - JSON - - Object { 1..N One occurrence per product. JSON Object - - partNumber M Initial Order SKU for renewable subscription. String - Free Text 18 128I1-WW4421- T056 partnerSubscriptionId O Optional when Adding Products. Can NOT be String - Free Text 40 42e0e7d0-e7d7- sent when Adding Seats. 408a-8471- bb2acc62fbc2 Fresh value generated by the service caller. Formerly known as subscription Id.

• The subscription ID is alpha-numeric. • The subscription ID can contain a hyphen. • The subscription ID can contain a space. • The subscription ID does NOT need to be in UUID v4 format. subscriptionReferenceNumbe O Required for Add Seats. String - Free Text 40 563-04891896 r Formerly known as serial number Serial number of the product to modify. quantity M Number of seats. Number - Integer - 8 netPrice M Price for the line item. Please note that String - Free Text 20 230.50 quantity is a factor for the pricing.

AUTODESK PlaceOrder v2 Service Reference Manual 25

Please note that Pro-Rating may apply when adding seats or products in the middle of the contract term. See Table 13 for Pro-Rating logic. } - - - - - ] - - - - - orderDiscounts [ O List of Discounts to be applied. Array - JSON - - Object { 1..N One occurrence per discount. JSON Object - - discountId M Discount ID for approved Deal Discounts String - Free Text 15 A-3755776 (Opportunity number associated with the Deal Discount Number – 18 digit unique identifier) discountType M Type of discount being applied. Valid values: String - Free Text 20 DDA

DDA } - - - - ] - - - - Table 4: Detailed JSON Request Structure for Additions to existing Orders (Renewal)

AUTODESK PlaceOrder v2 Service Reference Manual 26

5.1.3.3 Renewal

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h action M Action to be performed by the service. String - Free Text 35 “Renewal”

For renewals its value has to be “Renewal” endCustomer { O Default End Customer information for the JSON Object - - order placed. contractManager {} O Contract Manager details should only be sent JSON Object - - if there is a new Contract Manager for the particular contract. If the Contract Manager is Please refer to unchanged, then there is no need for the Table 9 (Contact) partner to send the contract manager. for entity details. } - - - - - shipTo {} M Default Ship to Account for the order placed. JSON Object - -

AUTODESK PlaceOrder v2 Service Reference Manual 27

Must not be sent when “contractEndDate” is populated to extend the Contract. priceDate O Explicit price date to support the 3 days grace String - Date ISO 10 2016-01-20 period functionality 8601 format contractEndDate O Requested contract end date for renewal used String - Date ISO 10 2017-01-01 to extend the service contract to a specified 8601 format end-date.

If this field is passed, then opportunityNumber must not be sent.

Cannot include the Price Date (which is used for 3-day grace period order processing when trying to order using a recently changed price) when doing an extend order. lineItems [ M List of products to be added or modified. Array - JSON - - Object { 1..N One occurrence per product. JSON Object - - action O Required only when performing a True-up String - Free Text 35 “True-up” transaction. Its value must be “True-up” partNumber M Renew or True-up SKU String - Free Text 18 128I1-WW3497- T122 partnerSubscriptionId O Subscription ID of the product to renew. String - Free Text 40 d3a274b0-3bb4- Formerly known as subscriptionID 4f52-a39b- 11163bb09b0f subscriptionReferenceNumbe M Subscription Reference Number of the String - Free Text 40 563-04891896 r product to renew. Formerly known as the serial number. Must not be sent when performing a True-up transaction. quantity M Number of seats. Number - Integer - 5 netPrice M Price for the line item. Please note that String - Free Text 20 553.20 quantity is a factor for the pricing. } - - - - - ] - - - - -

AUTODESK PlaceOrder v2 Service Reference Manual 28 orderDiscounts [ O List of Discounts to be applied. Array - JSON - - Object Can be used when Renewing or Extending a contract. { 1..N One occurrence per discount. JSON Object - - discountId M Discount ID for approved Deal Discounts String - Free Text 15 A-3755776 (Opportunity number associated with the Deal Discount Number – 18 digit unique identifier) discountType M Type of discount being applied. Valid values: String - Free Text 20 DDA

DDA } - - - - ] - - - - Table 5: Detailed JSON Request Structure for Renew Orders

AUTODESK PlaceOrder v2 Service Reference Manual 29

5.1.3.4 Maintenance-to-Subscription Switch

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h action M Action to be performed by the service. String - Free Text 35 “Switch from Maintenance” For M2S its value has to be “Switch from Maintenance” endCustomer { O Default End Customer information for the JSON Object - - order placed. contractManager {} O Contract Manager details should only be sent JSON Object - - if there is a new Contract Manager for the particular contract. If the Contract Manager is Please refer to unchanged, then there is no need for the Table 9 (Contact) partner to send the contract manager. for entity details. } - - - - - shipTo {} M Default Ship to Account for the order placed. JSON Object - -

AUTODESK PlaceOrder v2 Service Reference Manual 30 contractTerm O String value of the unit of measurement the String - Free Text 15 Annual partner is ordering.

Term is annual (1 year), 2 year, or 3 year opportunityNumber M Represents the maintenance renewal String - Free Text 15 A-2845443 opportunity.

This is a required field for M2S switches. priceDate O Explicit price date to support the 3 days grace String - Date ISO 10 2016-01-20 period functionality 8601 format lineItems [ M List of products to be added or modified. Array - JSON - - Object { 1..N One occurrence per product. JSON Object - - partNumber M Renew SKU. String - Free Text 18 128I1-WW3497- T122 quantity M Number of seats. Number - Integer - 5 netPrice M Either the full price of the sku or the prorated String - Free Text 20 553.20 price if it is add to existing contract. partnerSubscriptionId O Subscription ID of the product to renew. String - Free Text 40 d3a274b0-3bb4- Formerly known as subscriptionID 4f52-a39b- 11163bb09b0f previousSubscriptions [ M Array of serial numbers to be switched. Array - JSON - - Object subscriptionReferenceNum M Subscription Reference Number of the String - Free Text 36 563-04891896 ber product to renew. Formerly known as the serial number. quantity O For future extension of this schema to Number - Integer - 7 support partial quantity but will not be validated for existing Switch Flow, as it is always assumed that all the quantity is switched with switch action. ] } - - - - - ] - - - - - Table 6: Detailed JSON Request Structure for M2S Orders

AUTODESK PlaceOrder v2 Service Reference Manual 31

5.1.3.5 Multi-User trade in

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h action M Action to be performed by the service. String - Free Text 35 “Multi-User Trade- In” For Multi-User trade in its value has to be “Multi-User Trade-In” endCustomer { O Default End Customer information for the JSON Object - - order placed. contractManager {} O Contract Manager details should only be sent JSON Object - - if there is a new Contract Manager for the particular contract. If the Contract Manager is Please refer to unchanged, then there is no need for the Table 9 (Contact) partner to send the contract manager. for entity details. } - - - - - shipTo {} M Default Ship to Account for the order placed. JSON Object - -

AUTODESK PlaceOrder v2 Service Reference Manual 32

for the switch. The contract can contain either term-based subscriptions or maintenance subscriptions for perpetual licenses. opportunityNumber M Represents the maintenance renewal String - Free Text 15 A-2845644 opportunity.

This is a required field for MU2SU switches. priceDate O Explicit price date to support the 3 days grace String - Date ISO 10 2016-01-20 period functionality 8601 format lineItems [ M List of products to be added or modified. Array - JSON - - Object { 1..N One occurrence per product. JSON Object - - partNumber M SKU to perform the Trade-in action. String - Free Text 18 128I1-WW3497- T122 quantity M Number of seats. Number - Integer - 5 netPrice M Price of the SKU/item discounted in case of 2 String - Free Text 13 553.20 for 1 or full SKU/items. partnerSubscriptionId O Subscription ID of the product to renew. String - Free Text 40 d3a274b0-3bb4- Formerly known as subscriptionID 4f52-a39b- 11163bb09b0f previousSubscriptions [ O List of the Multi-User subscriptions, identified Array - JSON - - by serialNumbers or Object subscriptionReferenceNumber, being exchanged for new Single-User subscriptions.

This array is optional but is required when a 2 for 1 offer is used. It is not needed for any full (normal) purchase of a subscription with a corresponding 2 for 1 offer.

A maximum of 23 individual unique line items are allowed to trade-in per part number. subscriptionReferenceNum M Subscription Reference Number of the String - Free Text 15 563-04891896 ber product to switch. Formerly known as the serial number.

AUTODESK PlaceOrder v2 Service Reference Manual 33

quantity O For future extension of this schema to Number - Integer - 7 support partial quantity but will not be validated for existing Switch Flow, as it is always assumed that all the quantity is switched with switch action. ] } - - - - - ] - - - - - Table 7: Detailed JSON Request Structure for Multi-User Trade-in Orders

AUTODESK PlaceOrder v2 Service Reference Manual 34

5.1.3.6 Account

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h csn O - String - Free Text 10 5256678474 name O Mandatory if csn is not provided, ignored String - Free Text 100 (*) Partner Inc. otherwise. altName O Mandatory if csn is not provided, ignored String - Free Text 35 - otherwise. addressLine1 O Mandatory if csn is not provided, ignored String - Free Text 35 1 Parkway Road otherwise. addressLine2 O Optional if csn is not provided, ignored String - Free Text 35 - otherwise. addressLine3 O Optional if csn is not provided, ignored String - Free Text 35 - otherwise. city O Mandatory if csn is not provided, ignored String - Free Text 35 San Jose otherwise. postalCode O Mandatory if csn is not provided, ignored String - Free Text 35 94604 otherwise. stateProvinceCode O Optional if csn is not provided, ignored String - Free Text 35 CA otherwise. countryCode O Mandatory if csn is not provided, ignored String - ISO 2 Digit 2 US otherwise. Country Code phoneNumber O Optional if csn is not provided, ignored String - Free Text 35 +11434337799 otherwise. Table 8: Account JSON Model

(*) note: Account.name, which is used for End-Customer and Ship-To company names, has a maximum allowed length of 100- chars, but due to a SAP limitation you will get a truncated name of 35-chars in the response of GetOrderDetails and GetInvoiceDetails services response. For GetOpportunity service and any other report, you will get the full-length name.

(**) note: Address information will be validated: Address, City, Country and Postal code need to exist and be valid. Order failure is expected in other cases.

AUTODESK PlaceOrder v2 Service Reference Manual 35

5.1.3.7 Contact

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h firstName M First name of the contact. String - Free Text 35 James lastName M Last name of the contact. String - Free Text 35 Peterson email M Email address of the contact. String - Free Text 80 James.peterson@n omail.com countryCode O Country of the contact. String - ISO 2 Digit 2 US Country Code language O Preferred language of the contact. String - ISO 2 Digit 35 EN Language Code Table 9: Contact JSON Model

(*) note: Special characters are not allowed for First and Last names, hence complete or partial failure of order is expected. The only allowed special characters are hyphen( ‘–‘ ) and underscore( ‘_ ‘ )

AUTODESK PlaceOrder v2 Service Reference Manual 36

5.2 Response

5.2.1 High-Level Entity Relationship model

The following figure represents the high-level response schema of the PlaceOrder service. For a detailed description of each item, please refer to section 5.2.2.

Figure 4: Response High-Level JSON Schema Model

AUTODESK PlaceOrder v2 Service Reference Manual 37

5.2.2 Detailed Response JSON Structure

The following table explains the schema for the Response of the API service.

* Please note that Bold elements denote Groups. Plain elements denote Input Fields.

Payload Structure Cardinalit Description / Condition Data Type Lengt Example y h transactionId M The unique integer used in the request to String - UUID 36 aed587eb-4ad3- identify the transaction. version 4 4ec2-8083- 822062d55a0b status M The status confirming if request event has String - Free Text 10 processing started processing or encountered an error.

Possible values are: • processing • error error O Error when processing the event, if any. JSON Object - - { - - - - - code O Error code associated with error message. String - Free Text 5 43003

Please check section 8 for error codes and descriptions. message O Human readable message explaining error String - Free Text 50 Enter a valid action

Please check section 8 for error codes and descriptions. } - - - - - Table 10: Detailed JSON Response Structure

AUTODESK PlaceOrder v2 Service Reference Manual 38

6 Sample Requests/Responses

Sample requests are provided below as a reference. Please note that there are lots of other combinations possible.

6.1 Initial Order

Below is a sample request for an initial, renewable order with one product subscription.

Request POST /v2/orders/fulfillment HTTP/1.1 Host: enterprise-api-stg.autodesk.com Authorization: Bearer EJHZpIWBkdQPecjwVhLylKGDOtMF Content-Type: application/json signature: eDHyiqdugOMZTJwcvXFlrb/YycqvIMfgBSKhWEptVoR= timestamp: 1481139061 CSN: 0013284960

{ "action": "Initial", "endCustomer": { "account": { "name": "Padberg-Boyle", "addressLine1": "9451 Lee Hwy", "addressLine2": "Apt:617", "city": "Fairfax", "stateProvinceCode": "VA", "postalCode": "22031", "countryCode": "US" }, "contractManager": { "firstName": "Pearlie", "lastName": "Christiansen", "email": "[email protected]", "language": "EN", "countryCode": "US" } }, "shipTo": { "name": "ABC End User", "addressLine1": "123 Main Street", "addressLine2": "Building A", "city": "San Francisco",

AUTODESK PlaceOrder v2 Service Reference Manual 39

"stateProvinceCode": "CA", "postalCode": "94105", "countryCode": "US" }, "reseller": { "csn": "0070176510" }, "soldTo": { "csn": "0070176510" }, "poNumber": "2017-08-01-9678071455770702", "customerPoNumber": "2017-08-01-5521607100752069", "lineItems": [{ "partNumber": "001I1-WW1518-T316", "partnerSubscriptionId": "f2072540-4713-42c4-89bb-52bc6862db7a", "quantity": 1, "netPrice": "497.25" } ] }

Response with no errors { "transactionId": "b982c66e-0a02-4c7a-a920-f6d94a37888c", "status": "processing" }

Response with errors { "transactionId": "f23d640e-ed49-4f8b-83fb-d549c15aaef2", "status": "error", "error": { "code": 43033, "message": "Enter a valid price for Part Number 001I1-WW1518-T316" } }

AUTODESK PlaceOrder v2 Service Reference Manual 40

6.2 Additions – Add seats

Below is a sample addition request for adding more seats to one product of an existing, renewable contract.

{ "action": "Add-On", "endCustomer":{ "contractManager":{ "firstName":"John", "lastName":"Smith", "email":"[email protected]", "language":"EN", "countryCode":"US" } }, "shipTo":{ "name":"AB Devillers", "addressLine1":"1482 spicetree circle", "addressLine2":"Apt:203", "city":"Fairborn", "stateProvinceCode":"OH", "postalCode":"45324", "countryCode":"US" }, "reseller":{ "csn":"0070176510" }, "soldTo":{ "csn":"0070176510" }, "customerPoNumber":"2017-08-01-9678071455779977", "poNumber":"2017-08-01-9678071455776653", "contractNumber":"712100035873", "lineItems":[

AUTODESK PlaceOrder v2 Service Reference Manual 41

{ "partNumber":"001I1-WW1518-T316", "subscriptionReferenceNumber":"712-10050071", "quantity":1, "netPrice":"497.25" } ] }

Response with no errors { "transactionId": "7ec0f98e-116f-4fea-81a4-25257c28dd39", "status": "processing" }

Response with errors { "transactionId": "9f387ef1-fd89-4e03-a70d-1f6394ecae45", "status": "error", "error": { "code": "status_failed", "message": "No asset on agreement for corresponding subscriptionReferenceNumber 123-434343 in line items" } }

6.3 Additions – Add products

Below is a sample addition request for adding one product to an existing, renewable contract.

{ "action": "Add-On", "endCustomer":{

AUTODESK PlaceOrder v2 Service Reference Manual 42

"contractManager":{ "firstName":"John", "lastName":"Smith", "email":"[email protected]", "language":"EN", "countryCode":"US" } }, "shipTo":{ "name":"AB Devillers", "addressLine1":"1482 spicetree circle", "addressLine2":"Apt:203", "city":"Fairborn", "stateProvinceCode":"OH", "postalCode":"45324", "countryCode":"US" }, "reseller":{ "csn":"0070176510" }, "soldTo":{ "csn":"0070176510" }, "customerPoNumber":"2017-08-01-9678071455779977", "poNumber":"2017-08-01-9678071455776653", "contractNumber":"712100035873", "lineItems":[ { "partNumber":"834I1-WW1518-T316", "partnerSubscriptionId":"36b91fc0-06ba-4ee2-a1f4-093268e7d8c6", "quantity":1, "netPrice":"211.75" } ] }

Response with no errors { "transactionId": "466f482a-49cd-4e61-9d8f-88a3fa217a0f", "status": "processing" }

Response with errors { "transactionId": "112e5a87-6983-4512-b847-e13b2e9092e4",

AUTODESK PlaceOrder v2 Service Reference Manual 43

"status": "error", "error": { "code": 43015, "message": "Part Number 827I1-WW1060-T725 does not exist" } }

6.4 Renewals

Below is a sample request for the renewal of a contract. The proper renew SKU should be used by the caller.

AUTODESK PlaceOrder v2 Service Reference Manual 44

"soldTo": { "csn": "0070176510" }, "poNumber": "2017-08-01-9678071455771112", "customerPoNumber": "2017-08-01-9678071455774556", "contractNumber": "712100035873", "opportunityNumber": "A-2010676", "lineItems": [{ "partNumber": "001I1-006414-T772", "subscriptionReferenceNumber": "712-10050071", "quantity": 1, "netPrice": "485.55" } ] }

Response with no errors { "transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95", "status": "processing" }

Response with errors { "transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a", "status": "error", "error": { "code": 43001, "message": "Unable to retrieve opportunity details" } }

6.5 Premium Renewals and True-ups

Below is a sample request for the renewal of a contract. The proper renew SKU should be used by the caller.

AUTODESK PlaceOrder v2 Service Reference Manual 45 timestamp: 1481139061 CSN: 0013284960

{ "action": "Renewal", "endCustomer": { "contractManager": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "language": "EN", "countryCode": "US" } }, "shipTo": { "name": "Test customer", "addressLine1": "500 California st", "addressLine2": "Omni building", "city": "San Francisco", "stateProvinceCode": "CA", "postalCode": "94104", "countryCode": "US" }, "reseller": { "csn": "0070176510" }, "soldTo": { "csn": "0070176510" }, "poNumber": "{{po_number1}}", "customerPoNumber": "CustPO-{{po_number1}}", "contractNumber": "Service Contract", "opportunityNumber": "ROM Opportunity", "lineItems": [{ "partNumber": "Renewal SKU from Opportunity for subscription", "subscriptionReferenceNumber": "Premium-Subscription", "quantity": 50, "netPrice": "1234.55" }, { "action": "True-up", "partNumber": "True-up SKU", "quantity": 1, "netPrice": "2833.33" } ] }

AUTODESK PlaceOrder v2 Service Reference Manual 46

Response with no errors { "transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95", "status": "processing" }

Response with errors { "transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a", "status": "error", "error": { "code": 43001, "message": "Unable to retrieve opportunity details" } }

6.6 Positive extension

Below is a sample request for a positive extension of a contract.

Request POST /v2/orders/fulfillment HTTP/1.1 Host: enterprise-api-stg.autodesk.com Authorization: Bearer D1ujy7SZMkwQdHVao8nHSciPyIyo Content-Type: application/json signature: cfbAmFz/G5UplkBWacARragV19LGrTKRkarCS7K/tSQ= timestamp: 1571224738 CSN: 5070267085

{ "action": "Renewal", "shipTo": { "csn": "5130214616" }, "reseller": { "csn": "5070267085" }, "soldTo": { "csn": "5070267085" }, "customerPoNumber": "jordi123ext2", "poNumber": "jordi123ext2", "contractNumber": "110003450516",

AUTODESK PlaceOrder v2 Service Reference Manual 47

"contractEndDate": "2020-12-17", "lineItems": [{ "partNumber": "057I1-009704-T385", "subscriptionReferenceNumber": "566-44645383", "quantity": 3, "netPrice": "273" } ] }

Response with no errors { "transactionId": " 3005fc54-d074-4162-8ad5-8eaf731e8dfc", "status": "processing" }

Response with errors { "transactionId": "81018d24-279b-4a75-bb62-3cb50c57d4f9", "status": "error", "error": { "code": "43076", "message": "Contract End Date must be after the current contract end date" } }

6.7 Maintenance-to-Subscription switch

Below is a sample M2S request for switching from a Maintenance to a Subscription contract.

{ "action": "Switch from Maintenance", "endCustomer": {

AUTODESK PlaceOrder v2 Service Reference Manual 48

"contractManager": { "firstName": "John", "lastName": "Doe", "email": "[email protected]", "language": "EN", "countryCode": "US" } }, "shipTo": { "name": "ABC Tech Ltd.", "addressLine1": "500 California St", "addressLine2": "Suite 1234 ", " city ": " San Francisco ", " stateProvinceCode ": " CA ", " postalCode ": " 94104 ", " countryCode ": " US " }, " reseller ": { " csn ": " 0000001234 " }, " soldTo ": { " csn ": " 0070123456 " }, " poNumber ": " PO - 1234 ", " customerPoNumber ": " CUST - PO - 1234 ", " switchFromContractNumber ": " 110123456789 ", " opportunityNumber ": " A - 1234567 ", " lineItems ": [{ " partNumber ": " 001I1 - WW1518 - T316 ", " partnerSubscriptionId ": " bf862027 - 257a - 4c7a - 9c5d - 69f3516de5d0 ", " previousSubscriptions ": [{ " subscriptionReferenceNumber ": " 561 - 10123456 ", " quantity ": " 7 " }, { " subscriptionReferenceNumber ": " 561 - 10345678 ", " quantity ": " 9 " } ], " quantity ": " 16 ", " netPrice ": " 777 " } ] }

Response with no errors

AUTODESK PlaceOrder v2 Service Reference Manual 49

{ "transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95", "status": "processing" }

Response with errors { "transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a", "status": "error", "error": { "code":,43007 "message": "Enter a valid contract number" } }

6.8 Multi-User trade in

Below is a sample MU2SU request for switching from a Multi-User to a Single-User contract.

{ "action": "Multi-User Trade-In", "endCustomer": { "contractManager": {

AUTODESK PlaceOrder v2 Service Reference Manual 50

"countryCode": "US", "email": "[email protected]", "firstName": "Alexo", "lastName": "Brad", "language": "EN" } }, "shipTo": { "csn": "5138405974" }, "reseller": { "csn": "0070000010" }, "soldTo": { "csn": "0070176510" }, "poNumber": "PWS_V2IO_PO_SMMar132", "customerPoNumber": "PWS_V2IO_Mar132", "switchFromContractNumber": "110003654646", "opportunityNumber": "A-30092080", "lineItems": [{ "partNumber": "657L1-WW3C98-T813", "previousSubscriptions": [{ "subscriptionReferenceNumber": "567-19379034", "quantity": 1 } ], "quantity": 2, "netPrice": "1660.0" }, { "partNumber": "657L1-WW3C98-T813", "previousSubscriptions": [{ "subscriptionReferenceNumber": "567-19379133", "quantity": 1 } ], "quantity": 2, "netPrice": "1660" } ] }

Response with no errors { "transactionId": "f30b6c7a-9585-41d1-9411-834d170acd95",

AUTODESK PlaceOrder v2 Service Reference Manual 51

"status": "processing" }

Response with errors { "transactionId": "7e937dbf-ab52-4a28-b7cf-74c4908d333a", "status": "error", "error": { "code":,43007 "message": "Enter a valid contract number" } }

AUTODESK PlaceOrder v2 Service Reference Manual 52

7 Formatting standards

UUID Version 4 – Unique, randomly generated string https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_.28random.29

ISO 8601 – YYYY-MM-DD date format http://www.iso.org/iso/home/standards/iso8601.htm

ISO 639-1 – Two letter language code http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=22109

ISO 3166-1 alpha-2 format – two letter country code form http://www.iso.org/iso/country_codes

8 Error Messages

Prior to reaching Autodesk systems, the service validates the request for authorization of services and authentication of the requester. Below is a list of error codes and their mapping to messages for scenarios such as when a request is not authorized or if the requester is not authenticated.

8.1 System Error codes

The following table shows the system error codes generated for any system issues in the Autodesk environment and the respective error messages present in response messages.

HTTP Status Code Autodesk Internal Message Error Code 200 – OK 201 – Created 304 – Not Modified 400 – Bad Request Error: 4000 Incorrect or malformed request 401 – Error: 4100 No CSN was passed in the request Unauthorized 401 – Error: 4101 No HMAC Signature passed in the request Unauthorized 401 – Error: 4102 No HMAC Client ID passed in the request Unauthorized

AUTODESK PlaceOrder v2 Service Reference Manual 53

401 – Error: 4103 No HMAC Timestamp passed in the request Unauthorized 401 – Error: 4104 No Authorization passed in the request Unauthorized 401 – Error: 4105 Invalid token Unauthorized 401 – Error: 4106 Something went wrong generating the token Unauthorized 403 – Forbidden Error: 4301 HMAC signature was passed, but not a correct one 403 – Forbidden Error: 4302 HMAC timestamp was passed, but not a correct one 403 – Forbidden Error: 4300 CSN was passed, but not a correct one 504 – Gateway Error: 41013 Service request timeout Timeout Table 11: Authentication Error Codes

8.2 Service Error Codes

The table below lists the possible error codes returned by the PlaceOrder v2 Service due to Business Logic or Data related errors.

Error Code Error Message Error Description UAN-GEN- Please enter Customer Number Customer Number with blank 00108 value 43001 Enter a valid required entity/element for specified action (e.g. no Sold-To CSN provided by partner) • Partner exceeded character length of the entity/element in the message • Partner sent data in an incorrect format (e.g. sending a string when they were expected to send an integer, or sending dates

AUTODESK PlaceOrder v2 Service Reference Manual 54

in a format other than YYYY-MM-DD) • Partner did not group certain elements together (e.g. partner opted to send end customer account details in lieu of an end customer CSN and are missing the account name) 43002 Request Body Missing Request message body is empty or blank 43003 Enter a valid action Action is not sent by partners or Action is not a valid name/scenario 43005 Invalid Part Number {{0}} for • Part Number submitted by action partner is not applicable to initial orders • Part Number submitted by partner is not applicable to Add-On orders • Part Number submitted by partner is not applicable to Subscription Renewal or Maintenance Renewal orders 43006 Invalid line item offering Part Numbers submitted by combination partner are not the same subscription type (e.g. subscription renewal vs. maintenance renewal) 43007 Enter a valid contract number Contract Number submitted by partner does not exist in back office (e.g. Siebel, SFDC) 43008 SubscriptionReferenceNumber Subscription Reference Number {{0}} is not active submitted by partner is not an active subscription 43009 SubscriptionReferenceNumber Subscription Reference Number {{0}} does not exist on contract submitted by partner is not a subscription under the Contract Number submitted by partner

AUTODESK PlaceOrder v2 Service Reference Manual 55

43010 Subscription Id {{0}} does not Subscription ID submitted by exist on contract partner is not a subscription under the Contract Number submitted by partner 43011 Enter a valid Sold-To CSN Invalid Sold To CSN provided 43012 Enter a valid Sold-To CSN Partner CSN not provided by partner in HTTP request header (unlikely scenario, as CSN is used in upfront apigee validation) 43013 Contract Start Date cannot exceed Contact Start Date submitted by 31 days from today's date partner can at most be 31 days in the future from today's date 43014 Contract start date must be When specifying a future start greater or equal to order date. date, this must be greater than today’s date 43015 Part Number {{0}} does not exist Part Number submitted by partner does not exist or is not present in cache 43016 Part Number {{0}} billing behavior Part Number submitted by is not supported partner has a billing behavior that is not blank, renewal, or recurring 43017 Part Number {{0}} is not active Part Number submitted by partner is not released (a.k.a. incorrect Dchain Status) for that partner's Sales Org 43018 Subscription term must match for Part Numbers submitted by all line items partner do not have the same term (e.g. Quarterly, Annual, Multi-Year) 43019 Subscription term must match Part Numbers submitted by between all line items and partner do not have the same contract term (e.g. Quarterly, Annual, Multi-Year) & do not match with the Service Contract Number provided 43020 License model must match for all Part Numbers submitted by line items partner do not have the same License Model (e.g. Term) 43021 License model must match for all Part Numbers submitted by line items and contract partner do not have the same License Model & do not match

AUTODESK PlaceOrder v2 Service Reference Manual 56

with the Service Contract Number provided 43022 License usage type must match Part Numbers submitted by for all line items partner do not have the same License Usage Type (e.g. COM) 43023 License usage type must match Part Numbers submitted by for all line items and contract partner do not have the same License Usage Type & do not match with the Service Contract Number provided 43024 Billing behavior must match for Part Numbers submitted by all line items partner do not have the same Billing Behavior (e.g. renewable, auto-renew) 43025 Billing behavior must match for Part Numbers submitted by all line items and contract partner do not have the same billing behavior & do not match with the Service Contract's billing behavior 43026 Part Number {{0}} product line Part Number submitted by must match with subscription partner to add seats is not the product line same product line as the subscription the seats are being added to 43027 Part Number {{0}} support level Part Number submitted by must match with subscription partner to add seats is not the support level same subscription level as the subscription the seats are being added to 43028 Please submit another order for free month properties do not promotional items. match 43029 Part Number {{0}} has a free When modifying existing month agreement. New skus cannot have free months 43030 Reseller is not specialized for Part Sku has Special Sales Program Number(s) {{0}}, {{0}}, …, {{0}} 43031 Unable to verify renewal • No product list returned opportunity line items for opportunity • Product list is empty 43032 Part Number {{0}} does not meet Seat count provided by partner seat requirement for a given part number does not

AUTODESK PlaceOrder v2 Service Reference Manual 57

match the LPI opportunity seat threshold required for purchase 43033 Enter a valid price for Part Price for line item submitted by Number {{0}} partner does not match price records in cache 43035 Enter a valid Opportunity Number Opportunity Number submitted by partner either does not exist or the opportunity is in an invalid status (e.g. not Open, Ready for Order) 43036 Contract cannot be renewed Partner is attempting to renew a contract more than 90 days in advance of opportunity's asset end date or Partner can no longer renew the service contract as it is past the grace period (30 days after contract end date) 43037 Line items do not match Partner request line items are not opportunity line items to be in one-to-one with renewable line renewed items in the renewal opportunity specified (where oppty line item renew flag is set to 'TRUE') 43038 SubscriptionReferenceNumber Partner has submitted a {{0}} quantity does not match Subscription Reference Number opportunity line item quantity to to be renewed and the quantity be renewed they specified in their request message is not the quantity that is expected to be renewed 43039 Order has already been submitted Partner has submitted the same request/order to us and that previous order was created successfully 43040 Pricing not found for Part Number Part Number provided by partner {{0}} does not have pricing details for that partner's price list and price group 43041 Invalid Part Number {{0}} for Part Number submitted by subscription product line partner does not match the product line of the subscription it is attempting to modify

AUTODESK PlaceOrder v2 Service Reference Manual 58

43042 SubscriptionReferenceNumber Subscription ID generated and {{0}} does not exist on submitted by partner is not the subscription Subscription ID that already exists on the Subscription Reference Number 43043 Subscription term must match for Opportunity submitted by partner opportunity and contract does not have the same term (e.g. Quarterly, Annual, Multi-Year) as the Service Contract Number provided 43044 Product Line {{0}} on opportunity Partner did not send a part is missing in request number for a corresponding LPI opportunity product to be purchased 43063 Invalid opportunity status for Opportunity line item status is Subscription Reference Number not Open <> 43072 Price Date cannot be less than 3 The partner submitted a price days from today’s date date that was not less than 3 days from their current date (based on their timezone) 43073 Price Date cannot be in the future The partner submitted a future price date 43076 Contract End Date must be after When performing a contract the current contract end date positive extension, contract end date must be after current contract end date 43083 Cannot add seats to Subscription Start date in additions is limited Reference Number {{0}} that to Products. Cannot be used with begin with a future Contract Start seats. Date 43085 Contract Start Date cannot be When performing an Add Product after the current contract end with Future start date, this date date cannot be after current contract end date 43105 Subscription Reference Number Not every order line which is <> does not exist on renewing is present on opportunity opportunity 43114 Maximum Positive Extension End Customer is attempting to extend Date limit for Maintenance Maintenance products which will Products exceeded

AUTODESK PlaceOrder v2 Service Reference Manual 59

no longer be supported beyond certain future date 43115 Maximum Positive Extension End Customer is attempting to extend Date limit for Multi-User Products Multi-User products which will no exceeded longer be supported beyond certain future date 43116 Renewal of Premium Subscription Premium Subscription renewals is not allowed. Please contact are not allowed in PWS Client Services for Premium Renewal 43117 Extension of Premium Premium Subscription extensions Subscription is not allowed. For are not allowed in PWS questions please contact Client Services 43118 New Cloud Credits can only be Cloud Credits purchase through ordered with another product or PWS is not allowed without any added to an existing agreement other product on new contract 43120 Cannot co-term additional new Add seats does not support Cloud cloud credits to an existing Cloud Credits purchase Credit subscription. 43122 Mixed orders of Cloud Credits and Non-CCR/Add Product does not Non Cloud Credits are not support Cloud Credits purchase supported for Add-Product transaction 43124 Adding cloud credits is not M2S and Multi-user trade-in do currently supported with this not support Cloud Credits order action. purchase 43125 Cloud Credits are not supported Add-Product Future dated orders for future-dated Add-Product do not support Cloud Credits transaction purchase 43126 Cloud Credits Add-Product Clod Credits Add-Product Transactions are only allowed transactions can be done only on with an Active Contract Active Contract 43127 Add-On orders are not supported Add Product and Add Seats with Flex offerings transactions are not allowed for token packs on an existing agreement 50100 Internal Server Error • All unhandled exceptions • Unable to connect to downstream service Table 12: Application Error Codes

AUTODESK PlaceOrder v2 Service Reference Manual 60

8.3 Asynchronous Error Codes

Once the Order has been placed, asynchronous validations are executed in the Autodesk backend. Possible validation errors will be returned by the GetOrderStatus service. Please check the PWS_GetOrderStatus_Service Reference Manual for all possible error codes

Appendix A: Pro-Rating logic

Contract Logic Term !"#$%%&' Annual !"#$% = "'()* (,')-ℎ/ -' $')-"1$- %)* *1-%) × 4(1)-#-5 × !"# $! 12 !"#$%%&' 2-Years !"#$% = "'()* (,')-ℎ/ -' $')-"1$- %)* *1-%) × 4(1)-#-5 × !"# $! 24 !"#$%%&' 3-Years !"#$% = "'()* (,')-ℎ/ -' $')-"1$- %)* *1-%) × 4(1)-#-5 × !"# $! 36 Table 13: Pro-Rating Logic

Appendix B: Contract Extension policies (DRAFT)

• Extend via PWS only (for Subscription and M2S contracts. Extension of Maintenance contracts is available through PWS as well as AOE and Client Services) • No “negative extension” • Contract Extend is available for all contract type, provided the following conditions are met: o Contract is on an “active” status o The underlying product is eligible for renewal o The contract being extended is within the renewal window § In the event of extending multiple contracts at one time, at least one contract must be within the renewal window o Contract is extended to align to the end date of an existing contract • Contract Extend must be transacted with the appropriate Renewal SKU • Contracts will be extended using the current pricing at the time of the extension order • Add-ons must also be extended (ETR, Enterprise support)

AUTODESK PlaceOrder v2 Service Reference Manual 61

• Established proration rules apply. Extend orders are rounded up to full months and prorated 1/12 of yearly subscription for each month added to the Term • Partial extension is not supported • Established refund and return policies apply • Inappropriate use of extensions could impact Partner Agreement and/or related benefits/incentives

Appendix C: Multi-user Trade-in

Timelines

Beginning February 2020, we will be retiring subscriptions with multi-user access in a phased approach:

• February 29, 2020: o Announce changes o No new sales or renewals of 2 or 3-year multi-user subscriptions: Renew to annual term or take trade-in offer when available in May 2020 • May 7, 2020: o No new sales of 1-year multi-user subscriptions (full priced or discounted or discounted through M2S) or ETR (Extra Territory Rights): Renewals only o Multi-user trade-in launch: Trade-in 1 multi-user license for 2 standard subscriptions at a similar price to current date • May 7, 2021: o No renewals of 1-year multi-user subscriptions (full priced or discounted through M2S) or ETR: Must trade-in multi-user license or lose access to product

Transition

Customers trading in multi-user subscription seats are eligible for the multi-user trade-in. At their first renewal, starting May 7th 2020, customers can trade in each of their licenses and get 2 seats for 2 users on a named user plan - at a similar SRP they are paying today for the existing seat (i.e. if a customer has 20 seats on a retiring plan, they can trade them in for 40 seats on one of the named user plans at a similar SRP that they pay today. They will then renew those 40 seats at an ongoing discount until 2028).

AUTODESK PlaceOrder v2 Service Reference Manual 62

BEFORE AFTER

1 AutoCAD subscription

User User 1 AutoCAD seat

1 AutoCAD subscription

User User

1 multi-user AutoCAD seat 2 AutoCAD subscriptions for 2 users

Figure 5: before & after the Multi-user Trade-in

If the customer does not take the trade-in the first time around, then at their second renewal, they can still trade-in each of their seats to get one seat for one user on a standard plan at a similar price they are paying in 2019.

Multi-user Trade-in Starts Multi-user Trade-in Trade-in (1) multi-user or network When: Trade-in at your first renewal for a 2:1 offer maintenance seat or for (2) Standard * If you don’t take it then it will be a 1 for 1 trade-in at your second renewal subscriptions.

May 7, 2020 June 7, 2020 March 21, 2021 May 6, 2021 May 7, 2021

No renewals of: • multi-user subs • ETRs

Figure 6: Trade-in calendar

Once a customer transitions their seats will be on a Standard Plan, based on named user, with either a single product or industry collection.

The renewal SRP for subscriptions obtained through the trade-in offers will increase by no more than 5% in 2021, 2023, 2025, and 2027—with no changes in SRP for 2022, 2024, 2026 and 2028.

All customers taking a trade-in will have an ongoing renewal discount through until 2028. This applies to already discounted subscriptions and subscriptions at SRP that are traded in.

AUTODESK PlaceOrder v2 Service Reference Manual 63

Multi-user trade-in eligibility

Before taking the multi-user trade-in, the following conditions must be accomplished:

• Customer must own a: o Multi-user subscription o Discounted M2S Multi-user subscription o Network maintenance plan • Customer is in their renewal window for the license they want to trade-in • Customer has a product that is supported in single-user • Customer is willing to be current up to 3 previous versions (access, downloads and rights to use earlier than 3 previous will be lost) • Customer is willing to connect online every 30 days

Products not eligible for the multi-user trade-in offer

There are currently 20 products that will be excluded from Multi-user Trade-in offer.

If a customer is subscribed to any of the products listed here, they should continue to renew until further notice:

• Arnold • Autodesk Inventor Nastran • Autodesk Nastran • CFD Premium, Ultimate • Flame • Flame Assist • Flame Premium • Flare • Helius PFA • HSM – Premium, Ultimate • HSMWorks – Premium, Ultimate • Inventor ETO • InventorCAM – Premium, Ultimate • Lustre

AUTODESK PlaceOrder v2 Service Reference Manual 64

• Moldflow Adviser Premium, Ultimate • Moldflow Insight Standard, Premium, Ultimate • Moldflow Synergy • Netfabb Local Simulation • VRED Render Node • VRED Server

Appendix D: Premium Renewals and True-up use cases

True-up scenario with one Primary Admin and one Team:

Action Customer purchases Premium • Primary Admin: John and assigns it to a Primary o Team A: Admin § SUS Contract A

• AEC Collection 100

• Premium Contract P o Premium Subs1: 100 Before expiration, customer • Primary Admin: John adds more seats to their Team o Team A: § SUS Contract A • AEC Collection 100 § SUS Contract B • M&E Collection 50

• Premium Contract P o Premium Subs1: 100 Premium opportunity is • Opportunity Line Items: updated to reflect the o Premium Renewal1: 100 additional Premium eligible • True-up (John): seats o Premium Eligible Quantity: 150 o Premium Quantity: 100 o TrueUpDown Quantity: 50

AUTODESK PlaceOrder v2 Service Reference Manual 65

Partner places the renewal • Line 1 order o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 100 • Line 2 o Action: True-up o SKU: Premium True-up/Initial SKU o Quantity: 50

True-up scenario with one Primary Admin and multiple Teams

Action Customer purchases Premium • Primary Admin: John for their subscriptions o Team A: corresponding to different § SUS Contract A teams and assigns it to a • AEC Collection 100 Primary Admin o Team B: § SUS Contract B • M&E Collection 50

• Premium Contract P o Premium Subs1: 100 o Premium Subs2: 50 Before expiration, customer • Primary Admin: John adds more seats to Team A o Team A: § SUS Contract A • AEC Collection 100 § SUS Contract C • M&E Collection 25 o Team B: § SUS Contract B • M&E Collection 50

• Premium Contract P o Premium Subs1: 100 o Premium Subs2: 50

AUTODESK PlaceOrder v2 Service Reference Manual 66

Premium opportunity is • Opportunity Line Items: updated to reflect the o Premium Renewal1: 100 additional Premium eligible o Premium Renewal1: 50 seats • True-up (John): o Premium Eligible Quantity: 175 o Premium Quantity: 150 o TrueUpDown Quantity: 25 Partner places the renewal • Line 1 order o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 100 • Line 2 o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 50 • Line 3 o Action: True-up o SKU: Premium True-up/Initial SKU o Quantity: 25

True-up scenario with multiple Primary Admins

Action Customer purchases Premium • Primary Admin: John for their subscriptions o Team A: corresponding to different § SUS Contract A teams and assigns it to two • AEC Collection 100 different Primary Admins

• Primary Admin: Sara o Team B: § SUS Contract B • M&E Collection 50

• Premium Contract P o Premium Subs1: 100 – Team A o Premium Subs2: 50 – Team B

AUTODESK PlaceOrder v2 Service Reference Manual 67

Before expiration, customer • Primary Admin: John adds more seats to Team A o Team A: § SUS Contract A • AEC Collection 100 § SUS Contract C • M&E Collection 25

• Primary Admin: Sara o Team B: § SUS Contract B • M&E Collection 50

AUTODESK PlaceOrder v2 Service Reference Manual 68

Partner places the renewal • Line 1 order o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 100 • Line 2 o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 50 • Line 3 o Action: True-up o SKU: Premium True-up/Initial SKU o Quantity: 25

True-up scenario with multiple True-ups corresponding to multiple Primary Admins

• Primary Admin: Sara o Team B: § SUS Contract B • M&E Collection 50

• Premium Contract P o Premium Subs1: 100 – Team A o Premium Subs2: 50 – Team B Before expiration, customer • Primary Admin: John adds more seats to Team A and o Team A: Team B § SUS Contract A • AEC Collection 100 § SUS Contract C • M&E Collection 25

AUTODESK PlaceOrder v2 Service Reference Manual 69

• Primary Admin: Sara o Team B: § SUS Contract B • M&E Collection 50 § SUS Contract D • ACD Collection 75

• Premium Contract P o Premium Subs1: 100 – Team A o Premium Subs2: 50 – Team B Premium opportunity is • Opportunity Line Items: updated to reflect the o Premium Renewal1: 100 additional Premium eligible o Premium Renewal1: 50 seats • True-up (John): o Premium Eligible Quantity: 125 o Premium Quantity: 100 o TrueUpDown Quantity: 25 • True-up (Sara): o Premium Eligible Quantity: 50 o Premium Quantity: 50 o TrueUpDown Quantity: 75 Partner places the renewal • Line 1 order o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 100 • Line 2 o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 50 • Line 3 o Action: True-up o SKU: Premium True-up/Initial SKU o Quantity: 100

AUTODESK PlaceOrder v2 Service Reference Manual 70

True-down scenario with one Primary Admin and one Team:

Action Customer purchases Premium • Primary Admin: John and assigns it to a Primary o Team A: Admin § SUS Contract A

• AEC Collection 100 § SUS Contract B • AEC Collection 50

• Premium Contract P o Premium Subs1: 150 One of the lines expires • Primary Admin: John o Team A: § SUS Contract A • AEC Collection 100

• Premium Contract P o Premium Subs1: 150 Premium opportunity is • Opportunity Line Items: updated to reflect the o Premium Renewal1: 150 additional Premium eligible • True-up: seats o Premium Eligible Quantity: 100 o Premium Quantity: 150 o TrueUpDown Quantity: -50 During the time of renewal, • Opportunity Line Items: Partner requests/does an asset o Premium Renewal1: 100 split for Premium Subscription o Premium Renewal2: 50 corresponding to expired • True-up: underlying subscriptions o Premium Eligible Quantity: 100 o Premium Quantity: 150 o TrueUpDown Quantity: -50

AUTODESK PlaceOrder v2 Service Reference Manual 71

Partner places the renewal • Line 1 order o Action: Renewal o SKU: Premium Renewal SKU o Quantity: 100

• Existing renewal opportunity gets closed and a new renewal opportunity is created for the remaining Premium Subscription2 with 50 seats

AUTODESK PlaceOrder v2 Service Reference Manual 72