# Orders

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


**Note:** This doc is for the latest version of Chargebee Orders. If you enabled Chargebee Orders before _September-30-2018_ , you may be using the legacy version of the feature and its API. For help in migrating to the current system or using the legacy API for Chargebee Orders, please [contact support](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support)

Orders are automatically generated for an invoice when it gets paid, based on the shipping preference chosen for the invoice's product and the shipping date configuration. They can be updated either via api or merchant web console (a.k.a admin console).

## Sample Order

```json
{
  "created_at": 1517678686,
  "created_by": "full_access_key_v1",
  "deleted": false,
  "id": "__test__KyVnHhSBWlm1j2m7",
  "invoice_id": "__demo_inv__2",
  "object": "order",
  "order_type": "manual",
  "price_type": "tax_exclusive",
  "status": "new",
  "status_update_at": 1517678686
}
```

## Orders attributes

## Input Parameters

- `id` (required, string, max chars=40)
  Uniquely identifies the order. It is the api identifier for the order

- `document_number` (optional, string, max chars=50)
  The order's serial number

- `invoice_id` (optional, string, max chars=50)
  The invoice number which acts as an identifier for invoice and is generated sequentially.

- `subscription_id` (optional, string, max chars=50)
  The subscription for which the order is created

- `customer_id` (optional, string, max chars=50)
  The customer for which the order is created

- `status` (optional, enumerated string, default=new)
  The status of this order.
  Possible enum values:
    - `new`
      Order has been created. Applicable only if you are using Chargebee's legacy order management system.
    - `processing`
      Order is being processed. Applicable only if you are using Chargebee's legacy order management system
    - `complete`
      Order has been processed successfully. Applicable only if you are using Chargebee's legacy order management system
    - `cancelled`
      Order has been cancelled. Applicable only if you are using Chargebee's legacy order management system
    - `voided`
      Order has been voided. Applicable only if you are using Chargebee's legacy order management system
    - `queued`
      Order is yet to be processed by any system, these are scheduled orders created by Chargebee
    - `awaiting_shipment`
      The order has been picked up by an integration system, and synced to a shipping management platform
    - `on_hold`
      The order is paused from being processed.
    - `delivered`
      The order has been delivered to the customer.
    - `shipped`
      The order has moved from order management system to a shipping system.
    - `partially_delivered`
      The order has been partially delivered to the customer.
    - `returned`
      The order has been returned after delivery.

- `cancellation_reason` (optional, enumerated string)
  Cancellation reason
  Possible enum values:
    - `shipping_cut_off_passed`
      The invoice has been paid late and Chargebee cancel's the first order for the invoice.
    - `product_unsatisfactory`
      Product unsatisfactory.
    - `third_party_cancellation`
      Third party cancellation.
    - `product_not_required`
      Product not required.
    - `delivery_date_missed`
      Delivery date missed.
    - `alternative_found`
      Alternative found.
    - `invoice_written_off`
      The invoice has been completely written off. Orders are generated by Chargebee in cancelled state.
    - `invoice_voided`
      The invoice for which the order was createed has been voided.
    - `fraudulent_transaction`
      Fraudulent transaction.
    - `payment_declined`
      Payment declined.
    - `subscription_cancelled`
      The subsctiption for which the order was created has been cancelled.
    - `product_not_available`
      Product not available.
    - `others`
      Other reason
    - `order_resent`
      Order resent

- `payment_status` (optional, enumerated string)
  The payment status of the order
  Possible enum values:
    - `not_paid`
      NOT\_PAID
    - `paid`
      PAID

- `order_type` (optional, enumerated string)
  Order type
  Possible enum values:
    - `manual`
      The order has been created by the user using Chargebee's legacy order management system.
    - `system_generated`
      The order has been created by Chargebee automatically based on the preferences set by the user.

- `price_type` (required, enumerated string, default=tax_exclusive)
  The price type of the order
  Possible enum values:
    - `tax_exclusive`
      All amounts in the document are exclusive of tax.
    - `tax_inclusive`
      All amounts in the document are inclusive of tax.

- `reference_id` (optional, string, max chars=50)
  Reference id can be used to map the orders in the shipping/order management application to the orders in ChargeBee. The reference\_id generally is same as the order id in the third party application.

- `fulfillment_status` (optional, string, max chars=50)
  The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;

- `order_date` (optional, timestamp(UTC) in seconds)
  The date on which the order will start getting processed.

- `shipping_date` (optional, timestamp(UTC) in seconds)
  This is the date on which the order will be delivered to the customer.

- `note` (optional, string, max chars=600)
  The custom note for the order.

- `tracking_id` (optional, string, max chars=50)
  The tracking id of the order.

- `tracking_url` (optional, string, max chars=255)
  The tracking url of the order.

- `batch_id` (optional, string, max chars=50)
  Unique id to identify a group of orders.

- `created_by` (optional, string, max chars=50)
  The source (or the user) from where the order has been created.

- `shipment_carrier` (optional, string, max chars=50)
  Shipment carrier

- `invoice_round_off_amount` (optional, in cents, min=0)
  The total round off taken from the invoice level

- `tax` (optional, in cents, min=0)
  The total tax for the order.

- `amount_paid` (optional, in cents, min=0)
  Total amount paid for the order.

- `amount_adjusted` (optional, in cents, min=0)
  Total amount adjusted for the order.

- `refundable_credits_issued` (optional, in cents, min=0)
  The total amount issued as credits on behalf of this order.

- `refundable_credits` (optional, in cents, min=0)
  The total amount that can be issued as credits for this order.

- `rounding_adjustement` (optional, in cents)
  Rounding adjustment

- `paid_on` (optional, timestamp(UTC) in seconds)
  The timestamp indicating the date & time the order's invoice got paid.

- `shipping_cut_off_date` (optional, timestamp(UTC) in seconds)
  The time after which an order becomes unservicable

- `created_at` (required, timestamp(UTC) in seconds)
  The time at which the order was created

- `status_update_at` (optional, timestamp(UTC) in seconds)
  The time at which the order status was last updated.

- `delivered_at` (optional, timestamp(UTC) in seconds)
  The time at which the order was delivered

- `shipped_at` (optional, timestamp(UTC) in seconds)
  The time at which the order was shipped.

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

- `updated_at` (optional, timestamp(UTC) in seconds)
  The order's last modified time.

- `cancelled_at` (optional, timestamp(UTC) in seconds)
  The time at which the order was cancelled.

- `resent_status` (optional, enumerated string)
  Resent status of the order.
  Possible enum values:
    - `fully_resent`
      Order is Fully resent
    - `partially_resent`
      Order is Partially resent

- `is_resent` (required, boolean, default=false)
  Show if the order is resent order or not.

- `original_order_id` (optional, string, max chars=40)
  Refers to the original order id of the resent order.

- `discount` (optional, in cents, min=0)
  Total discount given for the order.

- `sub_total` (optional, in cents, min=0)
  The order's sub-total

- `total` (optional, in cents, min=0)
  Total amount charged for the order.

- `deleted` (required, boolean)
  Indicates that this resource has been deleted.

- `currency_code` (optional, string, max chars=3)
  The currency code (ISO 4217 format) for the invoice

- `is_gifted` (optional, boolean, default=false)
  Boolean indicating whether this order is gifted or not.

- `gift_note` (optional, string, max chars=500)
  The gift message added by the gifter during purchase

- `gift_id` (optional, string, max chars=50)
  The gift\_id if the order is a gift order

- `resend_reason` (optional, string, max chars=100)
  Reason code for resending the order. Must be one from a list of reason codes set in the Chargebee app in **Settings > Configure Chargebee > Reason Codes > Orders > Order Resend**. Must be passed if set as mandatory in the app. The codes are case-sensitive

- `business_entity_id` (optional, string, max chars=50)
  The unique ID of the [business entity](/docs/api/advanced-features) of this subscription. This is always the same as the [business entity](/docs/api/subscriptions/subscription-object#customer_id) of the customer.

- `order_line_items` (optional, list of order_line_item)
  The list of line items for this order.
  - `id` (required, string, max chars=40)
    The identifier for the order line item.
  - `invoice_id` (required, string, max chars=50)
    The invoice of the line item.
  - `invoice_line_item_id` (required, string, max chars=40)
    The invoice line item id associated with this order line item.
  - `unit_price` (optional, in cents, min=0)
    The unit price.
  - `description` (optional, string, max chars=250)
    The line item description.
  - `amount` (optional, in cents, min=0)
    The sub total, of the order line item
  - `fulfillment_quantity` (optional, integer, min=0)
    The quantity that is going to get fulfilled for this order
  - `fulfillment_amount` (optional, in cents, min=0)
    The amount that is going to get fulfilled for this order(amount after tax and discount)
  - `tax_amount` (optional, in cents, min=0)
    The total tax applied on this line item
  - `amount_paid` (optional, in cents, min=0)
    The total amount paid on the invoice, on behalf of this delivery
  - `amount_adjusted` (optional, in cents, min=0)
    The total amount adjusted on the invoice, on behalf of this delivery
  - `refundable_credits_issued` (optional, in cents, min=0)
    The total refundable credits issued on the invoice, on behalf of this delivery
  - `refundable_credits` (optional, in cents, min=0)
    The total amount issued as credits on behalf of this delivery
  - `is_shippable` (required, boolean)
    Appliable only if configured to include non shippable charges in orders, specifies if the charge is applicable for shipping
  - `sku` (optional, string, max chars=250)
    The SKU for the delivery.
  - `status` (optional, enumerated string, default=queued)
    The status of this order.
    Possible enum values:
      - `queued`
        Not processed for shipping yet.
      - `awaiting_shipment`
        Moved to shipping platform.
      - `on_hold`
        The delivery has been moved to "On hold" status.
      - `delivered`
        The order line item has been delivered.
      - `shipped`
        The order line item has been shipped.
      - `partially_delivered`
        The order has been partially delivered to the customer.
      - `returned`
        The order has been returned after delivery.
      - `cancelled`
        The order has been returned after delivery.
  - `entity_type` (required, enumerated string)
    Specifies the modelled entity ([plan](/docs/api/v2/pcv-1/plans/plan-object) / [addon](/docs/api/v2/pcv-1/addons/addon-object) etc) this line item is based on
    Possible enum values:
      - `adhoc`
        Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity\_id' attribute will be null in this case
      - `plan_item_price`
        Indicates that this line item is based on plan Item Price
      - `addon_item_price`
        Indicates that this line item is based on addon Item Price
      - `charge_item_price`
        Indicates that this line item is based on charge Item Price
  - `item_level_discount_amount` (optional, in cents, min=0)
    Item level discount amount
  - `discount_amount` (optional, in cents, min=0)
    The discount given on the order line item.
  - `entity_id` (optional, string, max chars=50)
    The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type

- `shipping_address` (optional, shipping_address)
  Shipping address for the order.
  - `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, India and UAE. 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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `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://chromium-i18n.appspot.com/ssl-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.

- `billing_address` (optional, billing_address)
  Billing address for the order.
  - `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, India and UAE. 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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `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://chromium-i18n.appspot.com/ssl-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_taxes` (optional, list of line_item_tax)
  The list of taxes applied on the order line items.
  - `line_item_id` (optional, string, max chars=40)
    The unique reference id of the line item for which the tax is applicable
  - `tax_name` (required, string, max chars=100)
    The name of the tax applied
  - `tax_rate` (required, double, default=0.0, min=0, max=100)
    The rate of tax used to calculate tax amount
  - `date_to` (optional, timestamp(UTC) in seconds)
    Indicates the service period end of the tax rate for the line item.
  - `date_from` (optional, timestamp(UTC) in seconds)
    Indicates the service period start of the tax rate for the line item.
  - `prorated_taxable_amount` (optional, bigdecimal, min=-1000000000, max=999999999.999999999)
    Indicates the prorated line item amount in cents.
  - `is_partial_tax_applied` (optional, boolean)
    Indicates if tax is applied only on a portion of the line item amount.
  - `is_non_compliance_tax` (optional, boolean)
    Indicates the non-compliance tax that should not be reported to the jurisdiction.
  - `taxable_amount` (required, in cents, min=0)
    Indicates the actual portion of the line item amount that is taxable.
  - `tax_amount` (required, in cents, min=0)
    The tax amount
  - `tax_juris_type` (optional, enumerated string)
    The type of tax jurisdiction
    Possible enum values:
      - `country`
        The tax jurisdiction is a country
      - `federal`
        The tax jurisdiction is a federal
      - `state`
        The tax jurisdiction is a state
      - `county`
        The tax jurisdiction is a county
      - `city`
        The tax jurisdiction is a city
      - `special`
        Special tax jurisdiction.
      - `unincorporated`
        Combined tax of state and county.
      - `other`
        Jurisdictions other than the ones listed above.
  - `tax_juris_name` (optional, string, max chars=250)
    The name of the tax jurisdiction
  - `tax_juris_code` (optional, string, max chars=250)
    The tax jurisdiction code
  - `tax_amount_in_local_currency` (optional, in cents, min=0)
    Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.
  - `local_currency_code` (optional, string, max chars=3)
    The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.

- `line_item_discounts` (optional, list of line_item_discount)
  The list of discounts applied for the order
  - `line_item_id` (required, string, max chars=50)
    The unique reference id of the line item for which the discount is applicable.
  - `discount_type` (required, enumerated string)
    Type of this discount line item
    Possible enum values:
      - `item_level_coupon`
        Represents the 'Item' level coupons applied to this invoice. Further the 'coupon\_id' attribute specifies the [coupon](/docs/api/coupons/coupon-object) id this discount is based on
      - `document_level_coupon`
        Represents the 'Document' level coupons applied to this document. Further the 'coupon\_id' attribute specifies the [coupon](/docs/api/coupons/coupon-object) id this discount is based on
      - `promotional_credits`
        Represents the Promotional Credits item in invoice. The 'coupon\_id' attribute will be null in this case
      - `prorated_credits`
        Represents the credit adjustment items in invoice. The 'coupon\_id' attribute will be null in this case
      - `custom_discount`
        Represents the discount applied on an resent order against the orginal order.
      - `item_level_discount`
        The deduction is due to a discount applied to a line item of the invoice. The discount id is available as the `entity_id`.
      - `document_level_discount`
        The deduction is due to a discount applied to the invoice `sub_total`. The discount id is available as the `entity_id`.
  - `entity_id` (optional, string, max chars=50)
    When the deduction is due to a `coupon` or a `[discount](/docs/api/getting-started)` , then this is the `id` of the coupon or discount.
  - `discount_amount` (required, in cents, min=0)
    Discount amount.

- `linked_credit_notes` (optional, list of order_line_item_linked_credit)
  The credit notes linked to the order
  - `amount` (optional, in cents, min=0)
    The amount issued for this order
  - `type` (required, enumerated string)
    The credit note type. [Learn more](/docs/api/credit_notes/credit-note-object) about credit note types.
    Possible enum values:
      - `adjustment`
        Adjustment Credit Note
      - `refundable`
        Refundable Credit Note
      - `store`
        Store Credit Note
  - `id` (required, string, max chars=50)
    Credit-note id.
  - `status` (required, enumerated string)
    The credit note status.
    Possible enum values:
      - `adjusted`
        When the Credit Note has been adjusted against an invoice.
      - `refunded`
        When the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded).
      - `refund_due`
        When the credits are yet to be used, or have been partially used.
      - `voided`
        When the Credit Note has been cancelled.
  - `amount_adjusted` (optional, in cents, min=0)
    Total amount adjusted on the order for the linked credit note. Applicable if the linked credit note is of the type 'adjustement'
  - `amount_refunded` (optional, in cents, min=0)
    Total refundable credits issued on the order for the linked credit note. Applicable if the linked credit note is of the type 'refundable'

- `resent_orders` (optional, list of resent_order)
  The list of resent orders applied on the order.
  - `order_id` (required, string, max chars=40)
    The order which is linked.
  - `reason` (optional, string, max chars=100)
    The order resent reason.
  - `amount` (optional, in cents, min=0)
    Value of the resent order.