Sales orders

API Version

Product Catalog

Library

Sales orders represent the contractual agreement and commitment for services between a seller and a buyer. They act as a seamless interface connecting any sales system (such as CPQ, CRM, or Customer Portal) with Chargebee Billing. The sales order captures the following essential components

Order Line Items including discounts and ramps
Billing and payment configuration
Contract terms and conditions
Customer information including billing and shipping contacts
Meta data

Sample sales order [ JSON ]

{}

API Index URL

https://{site}.chargebee.com/api/v2/sales_orders

id

string, max chars=50

External identifier of the sales order.

version

integer, default=1

Version of the sales order.

renewed_from_order_id

optional, string, max chars=50

The unique identifier of the original sales order from which this order was renewed. This field is used to track renewal orders and link them to their previous sales transactions.

updated_at

optional, timestamp(UTC) in seconds

Indicates the timestamp at which this sales order was last updated.

created_at

timestamp(UTC) in seconds

Timestamp indicating sales order created.

po_number

optional, string, max chars=100

Buyer's purchase order reference number.

meta_data

optional, string, max chars=65k

A set of key-value pairs stored as additional information for the subscription. Learn more .

quote_id

optional, string, max chars=100

Primary quote id for which the order was placed.

effective_date

timestamp(UTC) in seconds

Effective start date of the order signifies when the contract is signed and becomes legally binding.

end_date

optional, timestamp(UTC) in seconds

The date when the order is considered completed, cancelled, or no longer valid.

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this sales order.

customer_id

string, max chars=50

The unique ID of the customer to which this sales order belongs.

subscription_id

string, max chars=50

currency_code

string, max chars=3

The currency code (ISO 4217 format) of the sales order.

subscription_ids

optional, list of string

The unique identifiers of the subscriptions that are bundled as part of this sales order.

status

enumerated string, default=active

Status of the sales order.

Possible values are

line_items
Show attributes [+]

optional, list of line_item

Line items of this sales order

Line item attributes

id

string, max chars=50

External identifier of the sales order line item.

association_id

optional, string, max chars=105

A reference of line item to associate with other entities like line item tiers.

item_price_id

string, max chars=100

ID of the item price.

name

optional, string, max chars=100

Name of the item.

quantity

string, default=1, max chars=39

Quantity of the item.

unit_price

string, max chars=39

Unit price of the item.

billing_period

optional, integer, min=1

Defines billing period for the subscription item

billing_period_unit

optional, enumerated string

Defines billing period unit in association with the billing period.

Possible values are

service_period_days

optional, integer, min=1, max=730

The service period of the item in days from the day of charge.

charge_on_event

optional, enumerated string

When charge_on_option option is set to on_event , this parameter specifies the event at which the charge-item is applied to the subscription. This parameter only applies to charge-items.

Possible values are

charge_once

optional, boolean

Indicates if the charge-item is to be charged only once or each time the charge_on_event occurs. This parameter only applies to charge-items.

billing_cycles

optional, integer, min=0

Number of billing cycles for which this line item remains valid.

billing_type

enumerated string

Billing type of the item.

Possible values are

start_date

timestamp(UTC) in seconds

Start date of the line item.

end_date

optional, timestamp(UTC) in seconds

End date of the line item.

trial_end

optional, timestamp(UTC) in seconds

The date/time when the trial period of the item ends.

billing_addresses
Show attributes [+]

optional, list of billing_address

Billing address for a customer.

Billing address attributes

first_name

optional, string, max chars=150

The first name of the billing contact.

last_name

optional, string, max chars=150

The last name of the billing contact.

email

optional, string, max chars=70

The email address.

company

optional, string, max chars=250

The company name.

phone

optional, string, max chars=50

The phone number.

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

The name of the city.

state_code

optional, string, max chars=50

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ ). For Tamil Nadu (India), set as TN (not IN-TN ). For British Columbia (Canada), set as BC (not CA-BC ).

state

optional, string, max chars=50

State or Province

country

optional, string, max chars=50

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

discounts
Show attributes [+]

optional, list of discount

List of discounts for this subscription

Discount attributes

id

string, max chars=50

An immutable code for the discount. It is always auto-generated.

invoice_name

optional, string, max chars=100

The name of the discount as it should appear on customer-facing pages and documents such as invoices and hosted pages. This is auto-generated based on the type , amount , and currency_code of the discount. For example, it can be 10% off or 10$ off .

type

enumerated string, default=percentage

The type of discount. Possible value are:

Possible values are

apply_on

enumerated string

The amount on the invoice to which the discount is applied.

Possible values are

duration_type

enumerated string, default=forever

Specifies the time duration for which this discount is attached to the subscription.

Possible values are

percentage

optional, double, min=0.01, max=100.0

The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.

amount

optional, string, max chars=39

The value of the discount. The format of this value depends on the kind of currency. This is only applicable when discount.type is fixed_amount.

coupon_id

optional, string, max chars=50

ID/code of the coupon to be applied.

period

optional, integer, min=1

The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.

period_unit

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period.

Possible values are

item_price_id

optional, string, max chars=100

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.

start_date

timestamp(UTC) in seconds

Start date of the discount.

end_date

optional, timestamp(UTC) in seconds

End date of the discount.

shipping_addresses
Show attributes [+]

optional, list of shipping_address

Shipping address for the subscription.

Shipping address attributes

first_name

optional, string, max chars=150

The first name of the contact.

last_name

optional, string, max chars=150

The last name of the contact.

email

optional, string, max chars=70

The email address.

company

optional, string, max chars=250

The company name.

phone

optional, string, max chars=50

The phone number.

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

The name of the city.

state_code

optional, string, max chars=50

state

optional, string, max chars=50

The state/province name.

country

optional, string, max chars=50

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

line_item_tiers
Show attributes [+]

optional, list of line_item_tier

The pricing details of line_items which have pricing_model as tiered , volume or stairstep. Learn more about pricing models.

Line item tier attributes

starting_unit

string, max chars=39

The lowest value in the quantity tier.

ending_unit

optional, string, max chars=39

The highest value in the quantity tier.

price

string, max chars=39

The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.

pricing_type

optional, enumerated string

Pricing type for the tier.

Possible values are

package_size

optional, integer, min=1

Package size for the tier when pricing type is package. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.

line_item_association_id

optional, string, max chars=105

Association id of line item tho whom this line item tiers belongs.

payment_configuration
Show attributes [+]

optional, payment_configuration

Payment configuration of this sales order

billing_configuration
Show attributes [+]

optional, billing_configuration

Configurations controlling billing behavior and invoice generation workflows.

Billing configuration attributes

create_pending_invoices

optional, boolean

Indicates if pending invoices should be created.

invoice_immediately

optional, boolean

Indicates whether the invoices for this order are generated with a pending status.This attribute is set to true automatically when the subscription has item prices that belong to metered items.

first_invoice_pending

optional, boolean

Indicates if you want to bill the usages from the previous billing cycle. This creates a pending invoice immediately on subscription creation.

invoice_usages

optional, boolean

Setting this attribute to true would invoice the overages for the metered item during subscription changes

net_term_days

optional, integer

Net terms in days.

invoice_date

optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date.

billing_cycles_to_invoice

optional, integer

The number of billing cycles to be invoiced in advance for this order. If not specified, the invoice will be generated for the first billing cycle by default.

billing_alignment_mode

optional, enumerated string

Override the billing alignment mode for Calendar Billing. Only applicable when using Calendar Billing. The default value is that which has been configured for the site.

Possible values are

renewal_term
Show attributes [+]

optional, renewal_term

Renewal term for this sales order.

id

string, max chars=50

External identifier of the sales order.

version

integer, default=1

Version of the sales order.

renewed_from_order_id

optional, string, max chars=50

The unique identifier of the original sales order from which this order was renewed. This field is used to track renewal orders and link them to their previous sales transactions.

updated_at

optional, timestamp(UTC) in seconds

Indicates the timestamp at which this sales order was last updated.

created_at

timestamp(UTC) in seconds

Timestamp indicating sales order created.

po_number

optional, string, max chars=100

Buyer's purchase order reference number.

meta_data

optional, string, max chars=65k

A set of key-value pairs stored as additional information for the subscription. Learn more .

quote_id

optional, string, max chars=100

Primary quote id for which the order was placed.

effective_date

timestamp(UTC) in seconds

Effective start date of the order signifies when the contract is signed and becomes legally binding.

end_date

optional, timestamp(UTC) in seconds

The date when the order is considered completed, cancelled, or no longer valid.

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this sales order.

customer_id

string, max chars=50

The unique ID of the customer to which this sales order belongs.

subscription_id

string, max chars=50

currency_code

string, max chars=3

The currency code (ISO 4217 format) of the sales order.

subscription_ids

optional, list of string

The unique identifiers of the subscriptions that are bundled as part of this sales order.

status

enumerated string, default=active

Status of the sales order.

Possible values are

line_items

optional, list of line_item

Line items of this sales order

billing_addresses

optional, list of billing_address

Billing address for a customer.

discounts

optional, list of discount

List of discounts for this subscription

shipping_addresses

optional, list of shipping_address

Shipping address for the subscription.

line_item_tiers

optional, list of line_item_tier

The pricing details of line_items which have pricing_model as tiered , volume or stairstep. Learn more about pricing models.

payment_configuration

optional, payment_configuration

Payment configuration of this sales order

billing_configuration

optional, billing_configuration

Configurations controlling billing behavior and invoice generation workflows.

renewal_term

optional, renewal_term

Renewal term for this sales order.

Sample sales order [ JSON ]

API Index URL

Model Class

Sales order attributes

Consent Fields for Sales order

Custom Fields for Sales order