Sign in

v1

latestOpenAPI 3.0.32026-07-24614422630.2 KB
Orders

Create an order

creates an order with the specified parameters. On success the order id is returned.

post/orders

Query parameters

isDryRunboolean

indicates whether this order should be persisted.

populateMissingLinesboolean

indicates whether an amendment should populate missing lines not provided here.

Request body

idstring

System-generated unique identifier for the order.

externalIdstring

Unique external reference ID for the order that can be used for integration with other systems. This ID can't be reused on multiple orders.

namestring

Name or title of the order for easy identification.

accountIdstring

Unique identifier of the account associated with this order.

orderType'NEW' | 'AMENDMENT' | 'RENEWAL' | 'RESTRUCTURE' required

Type of order being placed. This value determines how the order will impact a subscription when it is executed.

Supported values:

  • NEW: Create a new subscription.
  • CANCEL: Cancel an existing subscription.
  • AMENDMENT: Amend an existing subscription.
  • RENEWAL: Renew an existing subscription.
  • RESTRUCTURE: Restructure an existing subscription.
paymentTerm'NET0' | 'NET30' | 'NET45' | 'NET60' | 'NET90'

Specifies when the payment for the invoice is due. Supported values are NET0, NET30, NET45, NET60, and NET90.

subscriptionIdstring

The ID of the subscription you want to amend, restructure, or cancel. To renew a subscription, use the renewalForSubscriptionId field to specify the ID of the subscription you want to renew. This field is not required while creating a new subscription.

shippingContactIdstring

ID of the contact to use for shipping information.

billingContactIdstring

ID of the contact to use for billing information.

startDateinteger required

Start date of the subscription in Unix timestamp format (seconds since epoch). This date is inclusive.

endDateinteger

End date of the subscription in Unix timestamp format (seconds since epoch). If not provided for TERMED subscriptions, it will be calculated based on termLength.

NOTE: This date is exclusive. For example, if the subscription's start date is 1735689600 (January 1, 2025 00:00:00) and the term length is 1 year, specify the end date as 1767225600 (January 1, 2026 00:00:00). Since the date is exclusive, the subscription is still active at December 31, 2025 23:59:59 but will have ended at January 1, 2026 00:00:00.

executedOninteger

Date when the order was executed in Unix timestamp format. Don't include this field if you're creating an order with orderType = NEW. This field is required only when you're creating an order to amend, renew, restructure, or cancel an existing subscription.

billingTerm'UP_FRONT' | 'IN_ARREARS'

Specifies when billing occurs relative to service delivery.

Supported values:

  • UP_FRONT: Billing occurs before the product or service is delivered
  • IN_ARREARS: The customer is billed after receiving the product or service.
billingAnchorDateinteger

Specific date to anchor billing cycles to, in Unix timestamp format (seconds since epoch). Useful for aligning billing with specific dates (e.g., first of the month).

rampIntervalinteger[]

Array of timestamps (in Unix timestamp format) defining intervals for ramped pricing schedules. Used when implementing gradual quantity or price changes over time.

orderFormTemplateIdsstring[]

Array of document template IDs to use for generating order forms. Specified as UUIDs.

sfdcOpportunityIdstring
isPrimaryOrderForSfdcOpportunityboolean
sfdcOpportunityNamestring
sfdcOpportunityTypestring
sfdcOpportunityStagestring
opportunityCrmType'SALESFORCE' | 'HUBSPOT'

Type of CRM where the opportunity is managed.

ownerIdstring

ID of the user who owns this order.

renewalForSubscriptionIdstring

ID of the subscription being renewed. Required only when orderType is RENEWAL.

documentMasterTemplateIdstring

UUID of the master document template to use for generating order documents.

purchaseOrderNumberstring

The purchase order number associated with this order.

purchaseOrderRequiredForInvoicingboolean

Indicates whether a purchase order number is required to generate an invoice.

autoRenewboolean

Indicates whether the subscription should automatically renew at the end of its term.

approvalSegmentIdstring

ID of the approval segment to use for routing this order through approval workflows.

attachmentIdstring

ID of an attachment associated with this order (e.g., signed contract).

compositeOrderIdstring
restructureForSubscriptionIdstring
expiresOninteger

Date when the order expires if the status is not EXECUTED. Specified in Unix timestamp format (seconds since epoch).

entityIdstring

ID of the entity (e.g., business or subsidiary) associated with this order.

startDateType'FIXED' | 'EXECUTION_DATE'

Determines how the start date is calculated.

NOTE: If you include the rampInterval object dates for a ramped pricing schedule, startDateType must be set to FIXED.

Supported values:

  • FIXED: Start date is the value of startDate, or the first rampInterval timestamp if specified.
  • EXECUTION_DATE: Start date is the date when the order status changes to EXECUTED.
currencystring

ISO 4217 currency code for the order. If you don't specify a value, the account's default currency is used.

subscriptionDurationModel'TERMED' | 'EVERGREEN'

Determines the subscription term.

Supported values:

  • TERMED: Subscription has a fixed term length.
  • EVERGREEN: Subscription continues indefinitely until cancelled.

Example request

{
  "id": "ORD-AXBY123",
  "externalId": "EXT-456789",
  "name": "CreativePro Monthly Subscription Order",
  "accountId": "ACCT-ADE4567",
  "orderType": "NEW",
  "paymentTerm": "NET30",
  "subscriptionId": "SUB-BCDE123",
  "shippingContactId": "CONT-XYZ7891",
  "billingContactId": "CONT-ABC1234",
  "startDate": 1672531200,
  "endDate": 1704067200,
  "executedOn": 1672617600,
  "billingTerm": "UP_FRONT",
  "billingAnchorDate": 1672531200,
  "opportunityCrmType": "SALESFORCE",
  "ownerId": "USR-12345AB",
  "renewalForSubscriptionId": "SUB-A1B3C4D",
  "documentMasterTemplateId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "purchaseOrderNumber": "123456789",
  "purchaseOrderRequiredForInvoicing": true,
  "approvalSegmentId": "APSG-ABC45",
  "attachmentId": "12345678",
  "expiresOn": 1675209600,
  "entityId": "ENT-98765AB",
  "startDateType": "EXECUTION_DATE",
  "currency": "USD",
  "subscriptionDurationModel": "TERMED"
}

Response

successful operation

idstring

System-generated unique identifier for the order.

entityIdstring

ID of the entity (e.g., business or subsidiary) associated with this order.

externalIdstring

Unique external reference ID for the order that can be used for integration with other systems. This ID can't be reused on multiple orders.

namestring

Name or title of the order for easy identification.

accountIdstring

Unique identifier of the account associated with this order.

orderType'NEW' | 'AMENDMENT' | 'CANCEL' | 'RENEWAL' | 'RESTRUCTURE' required

Type of order being placed. This value determines how the order will impact a subscription when it is executed.

Supported values:

  • NEW: Create a new subscription.
  • CANCEL: Cancel an existing subscription.
  • AMENDMENT: Amend an existing subscription.
  • RENEWAL: Renew an existing subscription.
  • RESTRUCTURE: Restructure an existing subscription.
currencystring

ISO 4217 currency code for the order. If you don't specify a value, the account's default currency is used.

paymentTerm'NET0' | 'NET30' | 'NET45' | 'NET60' | 'NET90'

Specifies when the payment for the invoice is due. Supported values are NET0, NET30, NET45, NET60, and NET90.

subscriptionIdstring

The ID of the subscription that you want to amend, restructure, or cancel.

subscriptionTargetVersioninteger

The subscription version targeted by this order. Each time a subscription is modified, the version is incremented. Orders target a specific version to maintain consistency. Orders may become outdated if the subscription is modified before the order is executed.

shippingContactIdstring

ID of the contact to use for shipping information.

billingContactIdstring

ID of the contact to use for billing information.

startDateinteger required

Start date of the subscription in Unix timestamp format (seconds since epoch). This date is inclusive.

endDateinteger

End date of the subscription in Unix timestamp format (seconds since epoch). If not provided for TERMED subscriptions, it will be calculated based on termLength.

NOTE: This date is exclusive. For example, if the subscription's start date is 1735689600 (January 1, 2025 00:00:00) and the term length is 1 year, specify the end date as 1767225600 (January 1, 2026 00:00:00). Since the date is exclusive, the subscription is still active at December 31, 2025 23:59:59 but will have ended at January 1, 2026 00:00:00.

billingTerm'UP_FRONT' | 'IN_ARREARS'

Specifies when billing occurs relative to service delivery.

Supported values:

  • UP_FRONT: Billing occurs before the product or service is delivered
  • IN_ARREARS: The customer is billed after receiving the product or service.
billingAnchorDateinteger

Specific date to anchor billing cycles to, in Unix timestamp format (seconds since epoch). Useful for aligning billing with specific dates (e.g., first of the month).

totalAmountnumber

Total currency amount for the order, including all line items, taxes, and discounts.

totalListAmountnumber

Total list amount for the order before any discounts are applied.

totalListAmountBeforeOverridenumber

Total list amount for the order before any manual overrides are applied.

taxEstimatenumber

Estimated tax amount for the order based on tax considerations.

status'DRAFT' | 'SUBMITTED' | 'APPROVED' | 'EXECUTED' | 'EXPIRED' required

Current status of the order. NOTE: Order details can be modified only when the status is DRAFT. When the order is in any other state, only a few attributes such as order name, shipping and billing contacts, PO number, and CRM opportunity details can be modified.

Supported values:

  • DRAFT: Initial and default status of an order. An order in this status can be modified.
  • SUBMITTED: Order has been submitted for review and approval. No further modifications are allowed without changing the order status back to DRAFT.
  • APPROVED: Order has been approved and is ready for execution.
  • EXECUTED: Order has been executed and the associated subscription has been created or modified.
  • EXPIRED: Order has reached its expiration date without being executed. You can change an expired order's status to DRAFT if the expiration date is removed or updated to a later date.
executedOninteger

Date when the order was executed in Unix timestamp format. This field is populated only when the order status is EXECUTED.

createdOninteger
updatedOninteger

Date when the order was last updated in Unix timestamp format (seconds since epoch).

executedOnFormattedstring

Formatted date when the order was executed.

rampIntervalinteger[]

Array of timestamps (in Unix timestamp format) defining intervals for ramped pricing schedules. The timestamps must be in chronological order from earliest to latest, and there must be no duplicate entries. Used when implementing gradual quantity or price changes over time.

orderFormTemplateIdsstring[]

Array of IDs associated with predefined terms used to generate order forms. Specified as UUIDs.

sfdcOpportunityIdstring

Salesforce opportunity ID associated with the order.

isPrimaryOrderForSfdcOpportunityboolean

Indicates if the order is the primary order for the Salesforce opportunity.

sfdcOpportunityNamestring

Salesforce opportunity name.

sfdcOpportunityTypestring

Type of Salesforce opportunity.

sfdcOpportunityStagestring

Stage of the Salesforce opportunity.

sfdcOrderCanBeExecutedboolean

Indicates whether the order can be executed in Salesforce.

opportunityCrmType'SALESFORCE' | 'HUBSPOT'

Type of CRM where the opportunity is managed.

renewalForSubscriptionIdstring

ID of the subscription being renewed. Returned only when orderType is RENEWAL.

renewalForSubscriptionVersioninteger

Version number of the subscription being renewed. Returned only when orderType is RENEWAL.

ownerIdstring

ID of the user who owns this order.

documentMasterTemplateIdstring

UUID of the document template to use to generate order documents.

purchaseOrderNumberstring

The purchase order number associated with this order.

purchaseOrderRequiredForInvoicingboolean

Indicates whether a purchase order number is required to generate an invoice.

autoRenewboolean

Indicates whether the subscription should automatically renew at the end of its term.

approvalSegmentIdstring

ID of the approval segment to use for routing this order through approval workflows.

attachmentIdstring

ID of an attachment associated with this order (e.g., signed contract).

compositeOrderIdstring

ID of the composite order. Returned only if this order is part of a composite order structure.

restructureForSubscriptionIdstring

ID of the subscription being restructured. Returned only when orderType is RESTRUCTURE.

expiresOninteger

Date when the order expires if the status is not EXECUTED. Specified in Unix timestamp format (seconds since epoch).

startDateType'FIXED' | 'EXECUTION_DATE'

Determines how the start date is calculated.

Supported values:

  • FIXED: Start date is the value of startDate, or the first rampInterval timestamp if specified.
  • EXECUTION_DATE: Start date is the date when the order status changes to EXECUTED.
customBillingEligibleOrderLineIdsstring[]

Array of line item IDs (i.e., charge IDs) in this order that are eligible for custom billing.

subscriptionDurationModel'TERMED' | 'EVERGREEN'

Determines the subscription term.

Supported values:

  • TERMED: Subscription has a fixed term length.
  • EVERGREEN: Subscription continues indefinitely until cancelled.

Example response

{
  "id": "ORD-AXBY123",
  "entityId": "ENT-98765AB",
  "externalId": "EXT-456789",
  "name": "CreativePro Monthly Subscription Order",
  "accountId": "ACCT-ADE4567",
  "orderType": "NEW",
  "currency": "USD",
  "paymentTerm": "NET30",
  "subscriptionId": "SUB-BCDE123",
  "subscriptionTargetVersion": 3,
  "shippingContactId": "CONT-XYZ7891",
  "billingContactId": "CONT-ABC1234",
  "startDate": 1672531200,
  "endDate": 1704067200,
  "billingTerm": "UP_FRONT",
  "billingAnchorDate": 1672531200,
  "totalAmount": 1500,
  "totalListAmount": 1800,
  "totalListAmountBeforeOverride": 2000,
  "taxEstimate": 120,
  "status": "APPROVED",
  "executedOn": 1672617600,
  "updatedOn": 1672704000,
  "executedOnFormatted": "2023-01-02T00:00:00Z",
  "opportunityCrmType": "SALESFORCE",
  "renewalForSubscriptionId": "SUB-A1B3C4D",
  "renewalForSubscriptionVersion": 2,
  "ownerId": "USR-12345AB",
  "documentMasterTemplateId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "purchaseOrderNumber": "123456789",
  "purchaseOrderRequiredForInvoicing": true,
  "approvalSegmentId": "APSG-ABC45",
  "attachmentId": "12345678",
  "compositeOrderId": "CORD-A0B0C1D",
  "restructureForSubscriptionId": "SUB-Z98Y7X6",
  "expiresOn": 1675209600,
  "startDateType": "EXECUTION_DATE"
}