Step 2: Update order

After creating the order, you may need to update some of the details before finalizing it. Use the Update order details endpoint to update an existing order that's in the DRAFT status.

🚧
Order status limits the changes you can make
When the order is in the DRAFT status, you can edit all order details. Once the order has transitioned to the SUBMITTED, APPROVED, or EXPIRED statuses, you can only update a subset of the order's attributes. Similarly, once an order is EXECUTED and a subscription is created, you can't change the details of the subscription without creating another order.

Prerequisites

To update an order, you'll need:

Your Subskribe API key.
The ID of the order you want to update. You can find the order ID in the response from the Create an order endpoint in Step 1: Create order.

Constructing the request body

The Update order details endpoint requires several parameters in the request body. Continuing with the example in Step 1 where we created an order for an annual software subscription, we want to update the order to purchase 20 licenses instead of the original 10. We also want to give the customer a discount of $20 per license, so we'll charge a per-unit price of $80 instead of $100. All other parameters of the order remain the same.

Required parameters

Note that some required parameter values remain the same as the ones we used during order creation. We'll only update the values requested by the customer.

New and updated parameters

id (new)

Type: string
- Value: ORD-91P88TH
- Details: This field identifies the order that you want to update. You can get this value from the order creation response in Step 1 .

lineItems (updated)

Type: object
Value:

  "lineItems": [
  {
      "chargeId": "CHRG-GTJ1X18", // Annual subscription charge
      "planId": "PLAN-FZNM5FF",
      "quantity": 20, // Changed from 10 to 20
      "discounts": [
          {
              "percent": 0.2 // 20% discount on per-unit price
          }
      ]
  },
  {
      "chargeId": "CHRG-25FW4WE",
      "planId": "PLAN-FZNM5FF",
      "quantity": 1
  }
]

Details: Array of line items in the order. In this example we have two array objects representing the two line items, but we're only updating the line item for the annual subscription charge. Regardless, we must include all line items in the request, even those that haven't changed.

Parameters with unchanged values

orderType

Type: string, enum
- Value: NEW . Supported values are NEW, CANCEL, AMENDMENT, RENEWAL, RESTRUCTURE.
- Details: Since we're creating a new order, set this to NEW.

startDate

Type: int64, Unix timestamp
- Value: 1735707600
- Details: Unix timestamp representation of January 01, 2025 00:00:00 UTC.

accountId

Type: string
- Value: ACCT-7N4VQ83
- Details: ID of the customer's account.

billingCycle

Type: object
Value:

  "billingCycle": {
    "cycle": "MONTH",
    "step": 1
  }

Details: How often you want to bill the customer. For this example, we want to bill the customer monthly.

billingTerm

Type: string, enum
- Value: IN_ARREARS. Supported values are UP_FRONT and IN_ARREARS.
- Details: Indicates whether billing occurs before or after service delivery.

paymentTerm

Type: string, enum
- Value: NET30. Supported values are NET0, NET30, NET45, NET60, and NET90.
- Details: Indicates when the invoice payment is due. For this example, we set NET30 indicating that the payment is due 30 days from the invoice date.

termLength

Type: object
Value:

  "termLength": {
    "cycle": "YEAR",
    "step": 1
  }

Details: The duration for which the customer's subscription should remain active. For this example, we want a one year subscription term.

Optional parameters

The request body to update an order must contain all the optional parameters that you included in the request to create the order.

❗️
If an optional parameter that was in your create order request body is missing from the update order request body, the value of that parameter will be overwritten.

We include the following parameters without changing any values:

name

Type: string
- Value: Annual software subscription
- Details: A descriptive name for the order.

subscriptionDurationModel

Type: string, enum
- Value: TERMED. Supported values are TERMED and EVERGREEN.
- Details: We use TERMED and specify details about the term using the termLength parameter.

currency

Type: string
- Value: USD
- Details: The currency to use for this order. If you don't specify this value, the order is created with the account's default currency.

For a complete list of parameters, refer to the Update order details endpoint documentation.

Sample request

The following sample shows a request to the Update order details endpoint with the request body parameters values set to make the required adjustments to the order details.

curl -X PUT "https://api.app.subskribe.com/orders" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderType": "NEW",
    "id": "ORD-91P88TH",
    "name": "Annual software subscription",
    "currency": "USD",
    "startDate": "1735707600",
    "accountId": "ACCT-7N4VQ83",
    "billingCycle": {
        "cycle": "MONTH",
        "step": 1
    },
    "billingTerm": "IN_ARREARS",
    "paymentTerm": "NET30",
    "subscriptionDurationModel": "TERMED",
    "termLength": {
        "cycle": "YEAR",
        "step": 1
    },
    "lineItems": [
        {
            "chargeId": "CHRG-GTJ1X18",
            "planId": "PLAN-FZNM5FF",
            "quantity": 20,
            "discounts": [
                {
                    "percent": 0.2
                }
            ]
        },
        {
            "chargeId": "CHRG-25FW4WE",
            "planId": "PLAN-FZNM5FF",
            "quantity": 1
        }
    ]
}'

Success response

The endpoint returns a 200 response code if the order details were updated successfully. You can use the Get order details endpoint to verify that the desired changes were made to the order.

Error handling

Error code	Error details	Recovery options
400 Bad Request	Order ID is null	The most likely cause is a missing `id` field in the request body. Try again with the ID of the order you want to update.
400 Bad Request	Percent value should be between 0 and 1	You likely specified the `discounts.percent` value incorrectly. For example, an 80% discount should be specified as `0.8`.
404 Not Found	Order does not exist	The `id` you specified in the request body refers to an order that doesn't exist. Try again with a valid order ID.