Step 1: Create order

Prerequisites

To create an order, you'll need:

Your Subskribe API key
Information about the plan(s) and associated charges you want to add to the order. These are known as lineItems in the order. To get a list of plans and charges, call the Get plans endpoint.

Constructing the request body

The Create order endpoint requires several parameters in the request body to define the order details, including the order type, account information, and line items.

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

The order 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 customer will be billed the full monthly amount of $1,500 in arrears throughout the year-long subscription term.

Required parameters

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.

lineItems

Type: object
Value:

   "lineItems": [
      {
          "chargeId": "CHRG-GTJ1X18", // ID of the charge
          "planId": "PLAN-FZNM5FF", // ID of the plan containing the charge
          "quantity": 10 // The quantity of items the customer wants to purchase
      },
      {
          "chargeId": "CHRG-25FW4WE",
          "planId": "PLAN-FZNM5FF",
          "quantity": 1
      }
  ]

Details: Array of line items or charges to add to the order. Note that you must list all charges in a plan. To get a list of plans and charges, call the Get plans endpoint.

Optional parameters

We also include the following optional parameters to provide additional order details:

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 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": "NEW",
    "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": 10
        },
        {
            "chargeId": "CHRG-25FW4WE",
            "planId": "PLAN-FZNM5FF",
            "quantity": 1
        }
    ]
}'

Examining the response

Upon successful creation, the API returns the complete order object with an assigned order ID and status set to DRAFT.

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: (Line 105 in the code sample below) The current status of the order. All new orders are created in the DRAFT status.
totalAmount: (Line 102 in the code sample below) 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 line item objects representing the changes that will be made to the subscription when the order is executed. Each line item object in this response has the action parameter set to ADD, indicating that these line items will be added to the subscription when it is created.

{
    "id": "ORD-91P88TH",
    "entityId": "ENT-6JN1BKJ",
    "name": "Annual software subscription",
    "accountId": "ACCT-7N4VQ83",
    "orderType": "NEW",
    "currency": "USD",
    "paymentTerm": "NET30",
    "subscriptionTargetVersion": 1,
    "lineItems": [
        {
            "id": "8c7997aa-f4d2-471e-9dae-8362b469a586",
            "isDryRunItem": false,
            "action": "ADD",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 10,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "amount": 1000.0000000000,
            "listAmount": 1000.0000000000,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "c9176373-02a9-4b39-a950-893187218e03",
            "isDryRunItem": false,
            "action": "ADD",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-25FW4WE",
            "quantity": 1,
            "isRamp": false,
            "listUnitPrice": 500.00000,
            "sellUnitPrice": 500.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "amount": 500.0000000000,
            "listAmount": 500.0000000000,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "lineItemsNetEffect": [
        {
            "id": "c9176373-02a9-4b39-a950-893187218e03",
            "isDryRunItem": false,
            "action": "ADD",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-25FW4WE",
            "quantity": 1,
            "isRamp": false,
            "listUnitPrice": 500.00000,
            "sellUnitPrice": 500.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "amount": 500.0000000000,
            "listAmount": 500.0000000000,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        },
        {
            "id": "8c7997aa-f4d2-471e-9dae-8362b469a586",
            "isDryRunItem": false,
            "action": "ADD",
            "planId": "PLAN-FZNM5FF",
            "chargeId": "CHRG-GTJ1X18",
            "quantity": 10,
            "isRamp": false,
            "listUnitPrice": 100.00000,
            "sellUnitPrice": 100.0000000000,
            "discountAmount": 0.00,
            "discounts": [],
            "amount": 1000.0000000000,
            "listAmount": 1000.0000000000,
            "effectiveDate": 1735707600,
            "endDate": 1767243600,
            "customFields": [],
            "dryRunItem": false
        }
    ],
    "startDate": 1735707600,
    "endDate": 1767243600,
    "termLength": {
        "cycle": "YEAR",
        "step": 1
    },
    "billingCycle": {
        "cycle": "MONTH",
        "step": 1
    },
    "billingTerm": "IN_ARREARS",
    "billingAnchorDate": 1735707600,
    "totalAmount": 1500.0000000000,
    "totalListAmount": 1500.0000000000,
    "totalListAmountBeforeOverride": 1500.0000000000,
    "status": "DRAFT",
    "updatedOn": 1756839999,
    "orderFormTemplateIds": [],
    "orderTerms": [],
    "isPrimaryOrderForSfdcOpportunity": false,
    "sfdcOrderCanBeExecuted": true,
    "renewalForSubscriptionVersion": 0,
    "purchaseOrderRequiredForInvoicing": false,
    "autoRenew": false,
    "customFields": [],
    "startDateType": "FIXED",
    "subscriptionDurationModel": "TERMED",
    "zeppaOutput": {
        "customizationRunSkipped": false,
        "customizationDefinitionMissing": true,
        "ruleTraces": []
    }
}

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.

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.