Create order

Use the POST /v3/customers/<customer-id>/orders endpoint to place an order for a customer. Read more about scenarios where an order is created.

Assumptions

Ensure that you are aware of the following before creating an order:

• orderType is required in the Create Order request.

  • Possible values are: NEW, RETURN, PREVIEW, PREVIEW_RENEWAL, or RENEWAL
  • See Order Scenarios for request and response samples for each order type.

• For renewal of an existing subscription, subscriptionId is mandatory in lineItems for:

  • orderType RENEWAL
  • orderType PREVIEW_RENEWAL if lineItems are present
  • Exception: an eligible early renewal after a currency change must use the new currency without the old subscription ID.

• referenceOrderId is required for RETURN orders and should not be included for other order types.

• For RETURN orders that reference a NEW or RENEWAL order, you can now return a quantity that is less than the original line item quantity, within 14 days of the original order. The requested quantity is validated against the line item’s current remainingQuantity value on the original order. See Return or cancellation of order for details on eligibility, exclusions, and error codes.

• currencyCode should now be sent at the lineItem level instead of the order level.

  • For backward compatibility, currencyCode can still be sent at the order level.

• The discountCode is applicable only to High Volume Discount customers who have migrated from VIP to VIP Marketplace. You can use the discount code only if their discount level in VIP is between 17 and 22.

• flexDiscountCodes can be used in the request to apply Flexible Discounts for customers who meet the eligibility criteria. For additional details, see Managing Flexible Discounts.

• Do not send an Adobe Instant Deal Registration code or ID. Adobe evaluates eligible line items automatically, independently of whether flexDiscountCodes is present.

  • When fetch-price=true, a qualifying response line item includes earnedDealRegPerUnit and earnedDealRegAmount in pricing, and pricingSummary includes totalEarnedDealRegAmount. These deal registration amounts remain separate from existing partner-price fields.

Orders after a country currency change

After a country transitions to a new currency, eligible customers place new orders and purchase additional seats in the new currency. These orders create new subscriptions in the new currency rather than adding licenses to existing subscriptions in the previous currency. For example, this applies when Canada transitions from USD to CAD or Mexico transitions from USD to MXN.

API requests for new orders, previews, manual renewals, early renewals, and license additions using the previous currency return CURRENCY_NOT_ACTIVE_FOR_COUNTRY with HTTP 422, subject to commitment exceptions.

Pre-cutover 3YC commitments retain their existing price list and currency until the commitment ends. Customers with an active pre-cutover 3YC commitment cannot place orders in the new currency during the commitment period. Returns and switch reverts retain the pricing and currency of the original order. See Local currency support for the complete lifecycle and commitment rules.

Request header

Reques body

Order resource without read-only fields:

{
  "externalReferenceId": "759", // (optional)
  "currencyCode": "USD", // (to be deprecated, use lineItem currencyCode)
  "orderType": "NEW | RETURN | PREVIEW | PREVIEW_RENEWAL | RENEWAL",
  "referenceOrderId": "", // (for returns only)
  "lineItems": [
    {
      "extLineItemNumber": 4,
      "offerId": "80004567EA01A12",
      "quantity": 1,
      "currencyCode": "USD",
      "deploymentId": "12345",
      "discountCode": "HVD_L18_PRE",
    },
  ],
}

Response

{
  "externalReferenceId": "759",
  "orderId": "0123456789",
  "customerId": "9876543210",
  "orderType": "NEW",
  "referenceOrderId": "",
  "currencyCode": "USD",
  "creationDate": "2019-05-02T22:49:54Z",
  "status": "1002",
  "source": "API",
  "lineItems": [
    {
      "extLineItemNumber": 4,
      "offerId": "80004567EA01A12",
      "quantity": 1,
      "subscriptionId": "",
      "status": "1002",
      "currencyCode": "USD",
      "deploymentId": "12345"
    }
  ],
  "links": {
    "self": {
      "uri": "/v3/customers/9876543210/orders/0123456789",
      "method": "GET",
      "headers": []
    }
  }
}

Notes:

• See Order Scenarios for request and response samples for each order type.
• See Order resource for descriptions for each request and response parameter.
• isDealRegistered is included only when Instant Deal Registration was auto-injected for a line item. If the field is absent, Instant Deal Registration was not injected or evaluated. A value of false means qualification failed; true means qualification passed. No amount fields are returned when the value is false.

HTTP status codes