# Sales orders

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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
{
  "id": "so__dev__KyVnQ2UfzGfdlQ",
  "version": 1,
  "created_at": 1742473843,
  "object": "sales_order",
  "effective_date": 1742377121,
  "end_date": 1837071521,
  "updated_at": 1742473843,
  "currency_code": "USD",
  "subscription_ids": [
    "__dev__KyVnQ2UfzGfjCU"
  ],
  "customer_id": "active_direct",
  "payment_configuration": {
    "auto_collection": "Off"
  },
  "billing_configuration": {
    "create_pending_invoices": false,
    "invoice_immediately": true,
    "net_term_days": 10,
    "billing_cycles_to_invoice": 1
  },
  "renewal_term": {
    "end_of_term_action": "renew",
    "billing_cycles_to_invoice": 3
  },
  "line_items": [
    {
      "id": "so_li__dev__KyVnQ2UfzGfe0R",
      "item_price_id": "netflix-prepaid-USD-Yearly",
      "quantity": "1",
      "unit_price": "100",
      "billing_period": 1,
      "billing_period_unit": "year",
      "billing_type": "recurring",
      "start_date": 1742377121,
      "end_date": 1773913121,
      "object": "line_item"
    },
    {
      "id": "so_li__dev__KyVnQ2UfzGfe3S",
      "item_price_id": "netflix-prepaid-USD-Yearly",
      "quantity": "1",
      "unit_price": "110",
      "billing_period": 1,
      "billing_period_unit": "year",
      "billing_type": "recurring",
      "start_date": 1773913121,
      "end_date": 1805449121,
      "object": "line_item"
    },
    {
      "id": "so_li__dev__KyVnQ2UfzGfe4T",
      "item_price_id": "netflix-prepaid-USD-Yearly",
      "quantity": "1",
      "unit_price": "121",
      "billing_period": 1,
      "billing_period_unit": "year",
      "billing_type": "recurring",
      "start_date": 1805449121,
      "end_date": 1837071521,
      "object": "line_item"
    }
  ],
  "shipping_addresses": [
    {
      "first_name": "s_a_first_name_1",
      "last_name": "s_a_last_name_1",
      "email": "shippingone@test.com",
      "company": "shipping one",
      "line1": "s_a_line_1",
      "city": "Ahd",
      "state_code": "GJ",
      "country": "IN",
      "zip": "380060",
      "type": "shipping",
      "object": "sales_order_address"
    }
  ],
  "billing_addresses": [
    {
      "first_name": "s_a_first_name_1",
      "last_name": "s_a_last_name_1",
      "email": "shippingone@test.com",
      "company": "shipping one",
      "line1": "s_a_line_1",
      "city": "Ahd",
      "state_code": "GJ",
      "country": "IN",
      "zip": "380060",
      "object": "sales_order_address"
    }
  ]
}
```

## Sales orders attributes

## Input Parameters

- `id` (required, string, max chars=50)
  External identifier of the sales order.

- `version` (required, 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` (required, 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](/docs/api/sales_orders) .

- `quote_id` (optional, string, max chars=100)
  Primary quote id for which the order was placed.

- `effective_date` (required, 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](/docs/api/getting-started) of this sales order.

- `customer_id` (required, string, max chars=50)
  The unique ID of the customer to which this sales order belongs.

- `subscription_id` (required, string, max chars=50)

- `currency_code` (required, string, max chars=3)
  The currency code (ISO 4217 format) of the sales order.

- `subscription_ids` (optional, string, max chars=50)
  The unique identifiers of the [subscriptions](/docs/api/subscriptions) that are bundled as part of this sales order.

- `status` (required, enumerated string, default=active)
  Status of the sales order.
  Possible enum values:
    - `active`
      active
    - `completed`
      completed

- `deleted` (required, boolean)

- `line_items` (optional, list of line_item)
  Line items of this sales order
  - `id` (required, 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` (required, string, max chars=100)
    ID of the item price.
  - `name` (optional, string, max chars=100)
    Name of the item.
  - `quantity` (required, string, default=1, max chars=39)
    Quantity of the item.
  - `unit_price` (required, string, max chars=39)
    Unit price of the item.
  - `billable_unit_price` (optional, string, max chars=39)
  - `billable_quantity` (optional, string, max chars=39)
  - `billable_amount` (optional, string, max chars=39)
  - `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 enum values:
      - `day`
        A period of 24 hours.
      - `week`
        A period of 7 days.
      - `month`
        A period of 1 calendar month.
      - `year`
        A period of 1 calendar year.
  - `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 enum values:
      - `subscription_creation`
        the time of creation of the subscription.
      - `subscription_trial_start`
        the time when the trial period of the subscription begins.
      - `plan_activation`
        same as subscription activation, but also includes the case when the plan-item of the subscription is changed.
      - `subscription_activation`
        the moment a subscription enters an `active` or `non-renewing` state. Also includes reactivations of canceled subscriptions.
      - `contract_termination`
        when a contract term is [terminated](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option) .
  - `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` (required, enumerated string)
    Billing type of the item.
    Possible enum values:
      - `recurring`
        Item gets billed at regular intervals
      - `one_time`
        Item gets billed once
      - `event_based`
        Item gets billed on specific events
  - `start_date` (required, 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.
  - `free_period` (optional, integer, min=1)
  - `free_period_unit` (optional, enumerated string)
    Possible enum values:
      - `day`
      - `week`
      - `month`
      - `year`

- `billing_addresses` (optional, list of billing_address)
  Billing address for a customer.
  - `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](https://www.iso.org/obp/ui/#search) 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](https://www.iso.org/iso-3166-country-codes.html) .
    
    **Note**: If you enter an invalid country code, the system will return an error.
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) 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](https://i18napis.appspot.com/address) .
  - `validation_status` (optional, enumerated string, default=not_validated)
    The address verification status.
    Possible enum values:
      - `not_validated`
        Address is not yet validated.
      - `valid`
        Address was validated successfully.
      - `partially_valid`
        The address is valid for taxability but has not been validated for shipping.
      - `invalid`
        Address is invalid.

- `discounts` (optional, list of discount)
  List of discounts for this subscription
  - `id` (required, 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](/docs/api/invoices) and [hosted pages](/docs/api/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` (required, enumerated string, default=percentage)
    The type of discount. Possible value are:
    Possible enum values:
      - `fixed_amount`
        The specified amount will be given as discount.
      - `percentage`
        The specified percentage will be given as discount.
      - `offer_quantity`
  - `apply_on` (required, enumerated string)
    The amount on the invoice to which the discount is applied.
    Possible enum values:
      - `invoice_amount`
        The discount is applied to the invoice `sub_total` .
      - `specific_item_price`
        The discount is applied to the `invoice.line_item.amount` that corresponds to the item price specified by `item_price_id` .
  - `duration_type` (required, enumerated string, default=forever)
    Specifies the time duration for which this discount is attached to the subscription.
    Possible enum values:
      - `one_time`
        The discount stays attached to the subscription till it is applied on an invoice **once**. It is removed after that from the subscription.
      - `forever`
        The discount is attached to the subscription and applied on the invoices till it is [explicitly removed](/docs/api/subscriptions/update-subscription-for-items#discounts_operation_type) .
      - `limited_period`
        The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by `period` and `period_unit` .
  - `percentage` (optional, double, min=0.01, max=100)
    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](/docs/api/currencies) 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 enum values:
      - `day`
        A period of 24 hours.
      - `week`
        A period of 7 days.
      - `month`
        A period of 1 calendar month.
      - `year`
        A period of 1 calendar year.
  - `item_price_id` (optional, string, max chars=100)
    The [id of the item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) in the subscription to which the discount is to be applied. Relevant only when `apply_on` = `specific_item_price`.
  - `start_date` (required, timestamp(UTC) in seconds)
    Start date of the discount.
  - `end_date` (optional, timestamp(UTC) in seconds)
    End date of the discount.

- `shipping_addresses` (optional, list of shipping_address)
  Shipping address for the subscription.
  - `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)
    The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search) 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)
    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](https://www.iso.org/iso-3166-country-codes.html) .
    
    **Note**: If you enter an invalid country code, the system will return an error.
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) 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](https://i18napis.appspot.com/address) .
  - `validation_status` (optional, enumerated string, default=not_validated)
    The address verification status.
    Possible enum values:
      - `not_validated`
        Address is not yet validated.
      - `valid`
        Address was validated successfully.
      - `partially_valid`
        The address is valid for taxability but has not been validated for shipping.
      - `invalid`
        Address is invalid.

- `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](https://www.chargebee.com/docs/plans.html#pricing-models) about pricing models.
  - `starting_unit` (required, 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` (required, 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 enum values:
      - `per_unit`
        Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
      - `flat_fee`
        Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the **stairstep** pricing model, `pricing_type` will be set to `flat_fee` by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
      - `package`
        Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
  - `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` (optional, payment_configuration)
  Payment configuration of this sales order
  - `auto_collection` (optional, enumerated string)
    Auto collection status.
    Possible enum values:
      - `on`
        on
      - `off`
        off
  - `payment_source_id` (optional, string, max chars=50)
    Identifier of the payment source for which this transaction is made
  - `payment_intent_id` (optional, string, max chars=150)
    Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
  - `offline_payment_method` (optional, enumerated string)
    The preferred offline payment method for the sales order.
    Possible enum values:
      - `no_preference`
        No Preference
      - `cash`
        Cash
      - `check`
        Check
      - `bank_transfer`
        Bank Transfer
      - `ach_credit`
        ACH Credit
      - `sepa_credit`
        SEPA Credit
      - `boleto`
        Boleto
      - `us_automated_bank_transfer`
        US Automated Bank Transfer
      - `eu_automated_bank_transfer`
        EU Automated Bank Transfer
      - `uk_automated_bank_transfer`
        UK Automated Bank Transfer
      - `jp_automated_bank_transfer`
        JP Automated Bank Transfer
      - `mx_automated_bank_transfer`
        MX Automated Bank Transfer
      - `custom`
        Custom

- `billing_configuration` (optional, billing_configuration)
  Configurations controlling billing behavior and invoice generation workflows.
  - `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.
  - `next_renewal_date` (optional, timestamp(UTC) in seconds)
  - `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 enum values:
      - `immediate`
        Subscription period will be aligned with the configured billing date immediately, with credits or charges raised accordingly..
      - `delayed`
        Subscription period will be aligned with the configured billing date at the next renewal.

- `renewal_term` (optional, renewal_term)
  Renewal term for this sales order.
  - `end_of_term_action` (required, enumerated string)
    The action at end of contract term
    Possible enum values:
      - `renew`
        -   Contract term completes and a new contract term is started for the number of billing cycles specified in [`renewal_billing_cycles`](/docs/api/sales_orders/sales_order-object#renewal_term_renewal_billing_cycles).
        -   The `end_of_term_action` for the new contract term is set to `renew`.
      - `cancel`
        Contract term completes and subscription is canceled.
      - `evergreen`
        Contract term completes and the subscription renews.
  - `cancellation_cutoff_period` (optional, integer)
    The number of days before contract\_end, during which the customer is barred from canceling the contract term. The customer is allowed to cancel the contract term via the Self-Serve Portal only before this period. This allows you to have sufficient time for processing the contract term closure.
  - `renewal_billing_cycles` (optional, integer)
    Specifies the number of billing cycles for which the contract will be renewed.

- `credit_lines` (optional, list of credit_line)
  - `amount` (required, string, max chars=39)
  - `unit_price` (required, string, default=0.00, max chars=39)
  - `quantity` (optional, string, max chars=33)
  - `line_item_association_id` (optional, string, max chars=105)

- `entitlement_overrides` (optional, list of entitlement_override)
  - `id` (required, string, max chars=50)
  - `feature_id` (required, string, max chars=50)
  - `entity_id` (required, string, max chars=100)
  - `entity_type` (required, enumerated string)
    Possible enum values:
      - `item_price`
      - `subscription`
  - `value` (optional, string, max chars=39)
  - `is_enabled` (required, boolean, default=true)
  - `start_date` (required, timestamp(UTC) in seconds)
  - `end_date` (optional, timestamp(UTC) in seconds)