Renew a subscription

To renew an expired subscription, create a new order with the RENEWAL order type and then execute it . You would typically create a renewal order when you want to renew an expired subscription without changing any of the underlying terms.

Prerequisites

To renew a subscription, you'll need:

Your Subskribe API key
The subscriptionId of the expired subscription.
The end date of the expired subscription.

👍
To get a list of all subscriptions and their details, call the Get paginated subscriptions endpoint.

Constructing the request body

In this example, we're renewing an expired subscription without changing any underlying subscription terms. Since the existing subscription already contains all the relevant details such as account ID, order line items, and billing terms, it's fairly easy to construct the API request body for a subscription renewal order.

Required parameters

To renew an expired subscription with the same underlying terms, we must include the following parameters in the request body:

orderType

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

renewalForSubscriptionId

Type: string
- Value: SUB-P9QGY5C
- Details: The ID of the subscription we want to renew. To get this value, call the Get paginated subscriptions endpoint.

startDate

Type: int64, Unix timestamp
- Value: 1758610800
- Details: The date on which you want the renewed subscription to become effective. NOTE: The start date of the renewed subscription must be the same as the end date of the expired subscription.

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": "RENEWAL",
    "renewalForSubscriptionId": "SUB-P9QGY5C",
    "startDate": "1758610800"
}'

Examining the response

If the request is successful, a new renewal 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, a renewal order is created in the DRAFT status. You need to execute the order to complete the subscription renewal.

Key fields in the response include:

id: The unique identifier for the order. We'll use this ID to make updates to the order in subsequent steps.
status: The current status of the order. All new orders, including renewal orders 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 charges that will become active when the renewed subscription takes effect.

Sample response body

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

{
    "id": "ORD-K7H9CP9",
    "entityId": "ENT-6JN1BKJ",
    "accountId": "ACCT-7N4VQ83",
    "orderType": "RENEWAL",
    "currency": "USD",
    "paymentTerm": "NET30",
    "subscriptionTargetVersion": 1,
    "shippingContactId": "CONT-KV8VPCJ",
    "billingContactId": "CONT-KV8VPCJ",
    "lineItems": [
        {
            "id": "fb5db540-0f35-4cdf-a6cf-29670de8dca8",
            "isDryRunItem": false,
            "action": "RENEWAL",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "ee5a5559-31da-4cac-982f-1981414ab080",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 10,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 1000.0000000000,
            "listAmount": 1000.0000000000,
            "effectiveDate": 1758610800,
            "endDate": 1790146800,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "4547cbee-8d26-4759-b386-c87a78fcdec0",
            "isDryRunItem": false,
            "action": "RENEWAL",
            "planId": "PLAN-FZNM5FF",
            "subscriptionChargeId": "6fb0c723-26ca-48fb-afb7-b4a565abb6a8",
            "chargeId": "CHRG-25FW4WE",
            "quantity": 1,
            "isRamp": false,
            "listUnitPrice": 500.00000,
            "sellUnitPrice": 500.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 500.0000000000,
            "listAmount": 500.0000000000,
            "effectiveDate": 1758610800,
            "endDate": 1790146800,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "lineItemsNetEffect": [
        {
            "id": "4547cbee-8d26-4759-b386-c87a78fcdec0",
            "isDryRunItem": false,
            "action": "RENEWAL",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-25FW4WE",
            "quantity": 1,
            "isRamp": false,
            "listUnitPrice": 500.00000,
            "sellUnitPrice": 500.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 500.0000000000,
            "listAmount": 500.0000000000,
            "effectiveDate": 1758610800,
            "endDate": 1790146800,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "fb5db540-0f35-4cdf-a6cf-29670de8dca8",
            "isDryRunItem": false,
            "action": "RENEWAL",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 10,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "predefinedDiscounts": [],
            "amount": 1000.0000000000,
            "listAmount": 1000.0000000000,
            "effectiveDate": 1758610800,
            "endDate": 1790146800,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "startDate": 1758610800,
    "endDate": 1790146800,
    "billingCycle": {
        "cycle": "MONTH",
        "step": 1
    },
    "billingTerm": "UP_FRONT",
    "billingAnchorDate": 1758610800,
    "totalAmount": 1500.0000000000,
    "totalListAmount": 1500.0000000000,
    "totalListAmountBeforeOverride": 1500.0000000000,
    "status": "DRAFT",
    "updatedOn": 1758648557,
    "orderFormTemplateIds": [],
    "orderTerms": [],
    "isPrimaryOrderForSfdcOpportunity": false,
    "sfdcOrderCanBeExecuted": true,
    "renewalForSubscriptionId": "SUB-P9QGY5C",
    "renewalForSubscriptionVersion": 1,
    "purchaseOrderRequiredForInvoicing": false,
    "autoRenew": false,
    "customFields": [],
    "startDateType": "FIXED",
    "zeppaOutput": {
        "customizationRunSkipped": false,
        "customizationDefinitionMissing": true,
        "ruleTraces": []
    }
}

Best practices

Use the isDryRun=true query parameter when creating orders to test without persisting them.
When creating a renewal 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 code	Error details	Recovery options
401 Unauthorized	Invalid API key	The most likely cause is that your API key is missing or it has expired. Try again with valid API credentials.
400 Bad Request	Missing required fields or request contains invalid values	See 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.
400 Bad Request	Start date should be the same as the subscription's end date	The start date for the renewed subscription should be the exact same as the end date of the expired subscription. To get the end date of the expired subscription, use the Get paginated subscriptions endpoint.