Guides

Amend a subscription

This tutorial walks you through the steps required to amend an existing subscription using the Subskribe API.

To amend an existing subscription, we create a new order with the AMENDMENT order type and then execute it. You would typically create an amendment order when you want to update the order quantities, amend the subscription start or end dates, or change the billing terms.

Prerequisites

To amend a subscription, you'll need:

  • Your Subskribe API key
  • The subscriptionId of the subscription you want to amend. To get a list of all subscriptions and their details, call the Get paginated subscriptions endpoint.
🚧

You can only make changes to subscriptions that are in the ACTIVE or PENDING states.

Constructing the request body

To amend an existing active subscription, we create a new order with the orderType parameter set to AMENDMENT. The Create order endpoint requires several parameters in the request body to define the amendment details, including the order type, account information, and line items.

In this example, we're amending an existing subscription for annual software licenses. The subscription is structured as a one-year termed contract starting on January 1, 2025.

The existing subscription includes two line items, i.e., charges belonging to the same plan:

  • A software license charge for 10 units at $100 each.
  • A premium service plan charge for 1 unit at $500.

The amendment requested by the customer is to increase the number of software licenses from 10 to 50 to accommodate their growing team.

All other subscription details including the billing term and billing frequency remain the same.

Required parameters

orderType
  • Type: string, enum
    • Value: AMENDMENT . Supported values are NEW, CANCEL, AMENDMENT, RENEWAL, RESTRUCTURE.
    • Details: Since we're creating an order to amend an existing subscription, set this to AMENDMENT.
subscriptionId
  • Type: string
    • Value: SUB-HV3MMMN
    • Details: The ID of the subscription we want to amend. To get this value, call the Get paginated subscriptions endpoint. Note that this value is not required to create a brand new order. It's required in this case since we're creating an order to amend an existing subscription.
startDate
  • Type: int64, Unix timestamp
    • Value: 1735707600
    • Details: Unix timestamp representation of January 01, 2025 00:00:00 UTC. Depending on the amendment details, this start date can stay the same as the one in the existing subscription, or you can update it to the date specified by the customer. You must include this value even if it is unchanged.
lineItems

Type: object

Details: Array of line items or charges that are already part of the subscription. These line item objects also contain updated details to reflect the amendment we want to make to the order. Note that you must list all line items that are in the plan.

While creating an amendment order, each line item must include the following parameters:

  • action: Indicates what action is performed on this charge. For the annual software license charge, we'll set this value to UPDATE, indicating that we're updating the details on an existing charge in the subscription. For the premium service plan charge, we'll set this value to NONE, indicating that we're not making any changes to this charge.

  • subscriptionChargeId: To get this value, call the Get paginated subscriptions endpoint and examine the response to get the charge.id value for the relevant subscription.

    Value:

   "lineItems": [
       {
           "chargeId": "CHRG-GTJ1X18", // ID of the annual software license charge
           "planId": "PLAN-FZNM5FF", // ID of the plan containing the charge
           "quantity": 50, // Updated license quantity from 10 to 50
           "action": "UPDATE", // Indicates that we're updating the line item
           "subscriptionChargeId": "3aced749-5fbd-4d03-a4e6-b71222ce8f5c" // ID of the subscription charge being updated
       },
       {
           "chargeId": "CHRG-25FW4WE", // ID of the premium service plan charge
           "planId": "PLAN-FZNM5FF",
           "action": "NONE", // Indicates that there's no change to this line item
           "subscriptionChargeId": "23008a5a-b34d-4f28-ad44-fa8799ad18f6",
           "quantity": 1
       }
  ]

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

Sample request

curl -X POST "https://api.app.subskribe.com/orders" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderType": "AMENDMENT",
    "name": "Amended annual software subscription",
    "subscriptionId": "SUB-HV3MMMN",
    "startDate": "1735707600",
    "lineItems": [
        {
            "chargeId": "CHRG-GTJ1X18",
            "planId": "PLAN-FZNM5FF",
            "quantity": 50,
            "action": "UPDATE",
            "subscriptionChargeId": "3aced749-5fbd-4d03-a4e6-b71222ce8f5c"
        },
        {
            "chargeId": "CHRG-25FW4WE",
            "planId": "PLAN-FZNM5FF",
            "action": "NONE",
            "subscriptionChargeId": "23008a5a-b34d-4f28-ad44-fa8799ad18f6",
            "quantity": 1

        }
    ]
}'

Examining the response

If the request is successful, a new amendment order is created. The API returns the complete order response object with a unique order ID and status set to DRAFT. See Sample response body

📘

Like all orders, an amendment order is created in the DRAFT status. You need to execute the order to complete the subscription amendment.

Key fields in the response include:

  • id: The unique identifier for the order.
  • status: The current status of the order. All new orders, including orders to amend existing subscriptions are created in the DRAFT status.
  • totalAmount: The total amount for the order that the customer will be invoiced for each month.
  • lineItems: The line items with their calculated amounts.
  • lineItemsNetEffect: Array of objects representing the changes that will be made to the line items in the subscription when the order is executed. In this example, the lineItemsNetEffect array contains two objects, both representing the changes made to the annual software license charge. See A closer look at lineItemsNetEffect for more details about this array. Note that the lineItemsNetEffect array doesn't list the premium service plan charge as we're not making any changes to it with this amendment order.

A closer look at lineItemsNetEffect

In this example where we're amending the annual software license charge, the lineItemsNetEffect array contains two objects representing this change (see the code sample below).

We're amending the quantity of licenses from 10 to 50. Rather than calculating a delta (+40), the platform uses a replacement approach:

  • The first line item (quantity = -10) removes the original subscription line item.
  • The second line item (quantity = 50) creates a new subscription line item with the updated quantity.

This approach simplifies billing reconciliation and audit trails by showing the complete removal of the old terms and addition of the new terms

"lineItemsNetEffect": [
        {
            "id": "efb97ca7-bc1a-4851-accb-e7fdea482a3d",
            "isDryRunItem": false,
            "action": "UPDATE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "3aced749-5fbd-4d03-a4e6-b71222ce8f5c",
            "subscriptionChargeGroupId": "dfca51fa-1fca-4b45-ba29-fa3b7e12ee74",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": -10,
          	{...}
            "dryRunItem": false
        },
        {
            "id": "1923921b-f956-432e-8539-3a3230cc5f8b",
            "isDryRunItem": false,
            "action": "UPDATE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeGroupId": "dfca51fa-1fca-4b45-ba29-fa3b7e12ee74",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 50,
          	{...}
            "dryRunItem": false
        }
    ],

Sample response body

The following code sample shows the full response from the Create an order endpoint for the amendment order.

{
    "id": "ORD-T9W336T",
    "entityId": "ENT-6JN1BKJ",
    "name": "Amended annual software subscription",
    "accountId": "ACCT-7N4VQ83",
    "orderType": "AMENDMENT",
    "currency": "USD",
    "paymentTerm": "NET30",
    "subscriptionId": "SUB-HV3MMMN",
    "subscriptionTargetVersion": 2,
    "lineItems": [
        {
            "id": "1923921b-f956-432e-8539-3a3230cc5f8b",
            "isDryRunItem": false,
            "action": "UPDATE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "3aced749-5fbd-4d03-a4e6-b71222ce8f5c",
            "subscriptionChargeGroupId": "dfca51fa-1fca-4b45-ba29-fa3b7e12ee74",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 50,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 0E-10,
            "listAmount": 0E-10,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "552455bd-20f1-4ef9-a291-719b2fb5aacd",
            "isDryRunItem": false,
            "action": "NONE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "23008a5a-b34d-4f28-ad44-fa8799ad18f6",
            "subscriptionChargeGroupId": "019e62d5-eabb-4d41-96b7-c7280218cc3f",
            "chargeId": "CHRG-25FW4WE",
            "quantity": 1,
            "isRamp": false,
            "listUnitPrice": 500.00000,
            "sellUnitPrice": 500.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 0E-10,
            "listAmount": 0E-10,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "lineItemsNetEffect": [
        {
            "id": "efb97ca7-bc1a-4851-accb-e7fdea482a3d",
            "isDryRunItem": false,
            "action": "UPDATE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "3aced749-5fbd-4d03-a4e6-b71222ce8f5c",
            "subscriptionChargeGroupId": "dfca51fa-1fca-4b45-ba29-fa3b7e12ee74",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": -10,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 0E-10,
            "listAmount": 0E-10,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "1923921b-f956-432e-8539-3a3230cc5f8b",
            "isDryRunItem": false,
            "action": "UPDATE",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeGroupId": "dfca51fa-1fca-4b45-ba29-fa3b7e12ee74",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 50,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 0E-10,
            "listAmount": 0E-10,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "startDate": 1735707600,
    "endDate": 1767243600,
    "termLength": {
        "cycle": "YEAR",
        "step": 1
    },
    "billingCycle": {
        "cycle": "MONTH",
        "step": 1
    },
    "billingTerm": "UP_FRONT",
    "billingAnchorDate": 1735707600,
    "totalAmount": 0E-10,
    "totalListAmount": 0E-10,
    "totalListAmountBeforeOverride": 0E-10,
    "status": "DRAFT",
    "updatedOn": 1758210393,
    "orderFormTemplateIds": [],
    "orderTerms": [],
    "isPrimaryOrderForSfdcOpportunity": false,
    "sfdcOrderCanBeExecuted": true,
    "renewalForSubscriptionVersion": 0,
    "purchaseOrderRequiredForInvoicing": false,
    "autoRenew": false,
    "customFields": [],
    "startDateType": "FIXED",
    "subscriptionDurationModel": "TERMED"
}

Best practices

  • Use the isDryRun=true query parameter when creating orders to test without persisting them.
  • For amendments, use the populateMissingLines=true parameter to include all existing subscription charges.
  • Set a reasonable expiresOn date for orders that need approval to prevent stale orders.
  • When creating an amendment, renewal, or restructure order, first retrieve the subscription details using the Get subscription details endpoint. If you need to retrieve the subscription ID first, use the Get paginated subscriptions endpoint.

Error handling

Error codeError detailsRecovery options
401 UnauthorizedInvalid API keyThe most likely cause is that your API key is missing or it has expired. Try again with valid API credentials.
400 Bad RequestMissing required fields or request contains invalid valuesSee the error response from the endpoint for recovery details that are specific to the cause of the error. This error may be caused due to one or more problems with the request body.

Updated 9 days ago

Did this page help you?