Sign in
Object Queries

Retrieve an order line item

Retrieve the details of a specific Order Line Item object.

get/object-query/order-line-items/{key}

Path parameters

keystring required

Object ID or Number.

Query parameters

pageSizeinteger

The maximum number of results to return in a single page. If the specified pageSize is less than 1 or greater than 99, Zuora will return a 400 error.

cursorstring

A cursor for use in pagination. A cursor defines the starting place in a list. For instance, if you make a list request and receive 100 objects, ending with next_page=W3sib3JkZXJ=, your subsequent call can include cursor=W3sib3JkZXJ= in order to fetch the next page of the list.

sort[]string[]

A case-insensitive query parameter that specifies the sort order of the list, which can be either ascending (e.g. accountnumber.ASC) or descending (e.g. accountnumber.DESC). You cannot sort on properties in arrays. If the array-type properties are specified for the sort[] parameter, they are ignored.

expand[]string[]

Allows you to expand responses by including related object information in a single call.

filter[]string[]

A case-insensitive filter on the list.

fields[]string[]

A case-insensitive query parameter that allows you to specify which fields are returned in the response.

includeNullFieldsboolean

Specifies whether to include fields with the null value in the response.

  • If set to true, all fields will be returned in the response, including those with the null value.
  • If set to false, only fields with non-null values will be returned.

Headers

Idempotency-Keystring

Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types.

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

Accept-Encodingstring

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encodingstring

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Zuora-Track-Idstring

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Zuora-Entity-Idsstring

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

Zuora-Org-Idsstring

Comma separated IDs. If you have <a href="https://docs.zuora.com/en/zuora-platform/organization-and-entity-management/multi-org/overview-of-multi-org" target="_blank">Zuora Multi-Org</a> enabled, you can use this header to specify which orgs to perform the operation in. If you do not have Zuora Multi-Org enabled, you should not set this header.

The IDs must be a sub-set of the user's accessible orgs. If you specify an org that the user does not have access to, the operation fails. This header is important in Multi-Org (MO) setups because it defines the organization context under which the API should operate—mainly used for read access or data visibility filtering. If the header is not set, the operation is performed in scope of the user's accessible orgs.

Zuora-Versionstring

The minor API version.

For a list of available minor versions, see API upgrades.

Response

OK

idstring

The unique identifier of the order line item.

createdByIdstring

The unique identifier of the user who created the order line item.

createdDatestring date-time

The time that the order line item gets created in the system, in the YYYY-MM-DD HH:MM:SS format.

updatedByIdstring

The unique identifier of the user who last updated the order line item.

updatedDatestring date-time

The date and time when the order line item was last updated.

accountingCodestring nullable

The accountingCode for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

billTargetDatestring date

The target date for the Order Line Item (OLI) to be picked up by bill run for generating billing documents.

To generate billing documents for an OLI, you must set this field and set the itemState field to SentToBilling.

You can update this field for a sales or return OLI only when the OLI is in the Executing state (when the itemState field is set as Executing).

amountPerUnitnumber

The actual charged amount per unit for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

descriptionstring

The description of the Order Line Item.

amountnumber

The total amount for the Order Line Item (OLI).

amountWithoutTaxnumber

The total amount for the Order Line Item (OLI) excluding tax.

itemNamestring

The name of the Order Line Item (OLI).

You can update this field for a sales or return OLI only when the OLI is in the Executing state (when the itemState field is set as Executing).

itemNumberstring

The number for the Order Line Item (OLI).

You can update this field for a sales or return OLI only when the OLI is in the Executing state (when the itemState field is set as Executing).

itemState'Executing' | 'Booked' | 'SentToBilling' | 'Complete' | 'Cancelled'

The state of the Order Line Item (OLI). See State transitions for an order, order line item, and fulfillment for more information.

To generate invoice for an OLI, you must set this field to SentToBilling and set the billTargetDate field .

You can update this field for a sales or return OLI only when the OLI is in the Executing or 'Booked' or SentToBillingstate (when the itemState field is set as Executing or SentToBilling).

itemType'Product' | 'Fee' | 'Services'

The type of the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

listPricePerUnitnumber

The list price per unit for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

listPricenumber

The extended list price for an order line item, calculated by the formula: listPrice = listPricePerUnit * quantity

orderIdstring

The ID of the order that the order line item belongs to.

orderNumberstring

The number of the order that the order line item belongs to.

productCodestring

The product code for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

purchaseOrderNumberstring

Used by customers to specify the Purchase Order Number provided by the buyer.

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

quantitynumber

The quantity of units, such as the number of authors in a hosted wiki service.

You can update this field for a sales or return OLI only when the OLI in the Executing state (when the itemState field is set as Executing).

revenueRecognitionRulestring

The Revenue Recognition rule for the Order Line Item.

productRatePlanChargeIdstring

ID of a Product Rate Plan Charge. Only one-time charges are supported.

billToIdstring

The ID of a contact that belongs to the billing account of the order line item. Use this field to assign an existing account as the bill-to contact of an order line item.

billToSnapshotIdstring

The snapshot of the ID for an account used as the bill-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The billToSnapshotId field is exposed while retrieving the order line item details.

shipTostring

The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the ship-to contact of an order line item.

shipToSnapshotIdstring

The snapshot of the ID for an account used as the ship-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The shipToSnapshotId field is exposed while retrieving the order line item details.

soldTostring

The ID of a contact that belongs to the owner acount or billing account of the order line item. Use this field to assign an existing account as the sold-to contact of an order line item.

soldToSnapshotIdstring

The snapshot of the ID for an account used as the sold-to contact of an order line item. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the order line item. The soldToSnapshotId field is exposed while retrieving the order line item details.

soldToOrderContactIdstring

The ID of the sold-to contact for the order.

ownerAccountIdstring

The account ID of the owner of the order line item.

invoiceOwnerAccountIdstring

The account ID of the invoice owner of the order line item.

taxCodestring

The tax code for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

taxMode'TaxInclusive' | 'TaxExclusive'

The tax mode for the Order Line Item (OLI).

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

transactionDatestring date

The date when the transaction occurs.

uOMstring

Specifies the units to measure usage.

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

relatedSubscriptionNumberstring

This field is used to relate an order line item to an subscription.

You can update this field only for a sales OLI and only when the sales OLI is in the Executing state (when the itemState field is set as Executing).

transactionEndDatestring date

The date a transaction is completed. The default value of this field is the transaction start date. Also, the value of this field should always equal or be later than the value of the transactionStartDate field.

You can update this field for a sales or return OLI only when the OLI is in the Executing state (when the itemState field is set as Executing).

transactionStartDatestring date

The date a transaction starts. The default value of this field is the order date.

You can update this field for a sales or return OLI only when the OLI is in the Executing state (when the itemState field is set as Executing).

excludeItemBillingFromRevenueAccountingboolean

Indicates whether to exclude the related invoice items, invoice item adjustments, credit memo items, and debit memo items from revenue accounting.

Note: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.

excludeItemBookingFromRevenueAccountingboolean

Indicates whether to exclude the related rate plan charges and order line items from revenue accounting.

Note: This field is only available if you have the Order to Revenue or Billing - Revenue Integration feature enabled.

originalOrderDatestring date

The date of the original sale order for a return order line item.

amendedByOrderOnstring date

The date of the amended order for a return order line item.

itemCategory'Sales' | 'Return'

The category of the Order Line Item, to indicate a product sale or return.

originalOrderIdstring

The ID of the original sale order for a return order line item.

originalOrderLineItemIdstring

The ID of the original sale order line item for a return order line item.

originalOrderLineItemNumberstring

The number of the original sale order line item for a return order line item.

originalOrderNumberstring

The number of the original sale order for a return order line item.

quantityAvailableForReturnnumber

The quantity that can be returned for an order line item.

quantityFulfillednumber

The fulfilled quantity for an order line item.

quantityPendingFulfillmentnumber

The quantity to fulfill for an order line item.

requiresFulfillmentboolean

The flag to show whether fulfillment is needed or not. It's derived from billing rule of the Order Line Item.

billingRule'TriggerWithoutFulfillment' | 'TriggerAsFulfillmentOccurs'

The billing rule of the Order Line Item.

inlineDiscountPerUnitnumber

This field is used in accordance with the inlineDiscountType field, in the following manner:

  • If the inlineDiscountType field is set as Percentage, this field specifies the discount percentage for each unit of the order line item. For exmaple, if you specify 5 in this field, the discount percentage is 5%.
  • If the inlineDiscountType field is set as FixedAmount, this field specifies the discount amount on each unit of the order line item. For exmaple, if you specify 10 in this field, the discount amount on each unit of the order line item is 10.

Once you set the inlineDiscountType, inlineDiscountPerUnit, and listPricePerUnit fields, the system will automatically generate the amountPerUnit field. You shall not set the amountPerUnit field by yourself.

inlineDiscountType'Percentage' | 'FixedAmount' | 'None'

This field is used to specify the inline discount type, which can be Percentage, FixedAmount, or None. The default value is Percentage.

This field is used together with the inlineDiscountPerUnit field to specify inline discounts for order line items. The inline discount is applied to the list price of an order line item.

Once you set the inlineDiscountType, inlineDiscountPerUnit, and listPricePerUnit fields, the system will automatically generate the amountPerUnit field. You shall not set the amountPerUnit field by yourself.

discountnumber

This field shows the total discount amount that is applied to an order line item after the inlineDiscountType, inlineDiscountPerUnit and quantity fields are set.

The inline discount is applied to the list price of an order line item.

recognizedRevenueAccountingCodeIdstring

The recognized revenue accounting code for the Order Line Item.

deferredRevenueAccountingCodeIdstring

The deferred revenue accounting code for the Order Line Item.

contractAssetAccountingCodestring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

contractLiabilityAccountingCodestring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

contractRecognizedRevenueAccountingCodeIdstring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

unbilledReceivablesAccountingCodeIdstring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

adjustmentRevenueAccountingCodeIdstring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

adjustmentLiabilityAccountingCodeIdstring

The accounting code on the Order Line Item object for customers using Zuora Billing - Revenue Integration.

Changes

No recorded changes to this endpoint across all 4 revisions of this API.