Line Items

The Line Item is an object used to represent some Product added to an Order. Line Item is validated against the product it is created from. Several properties (like name and description) are copied from the product, afterwards the relationship between products and line items is not maintained.

With every order, there might be any number of Line Items.

Line Items, Products and Orders are available only to users who are on the Enterprise plan.

Account’s administrators can disable changes to these entities in the account’s settings. When disabled, all data are preserved but only GET requests are allowed.

Properties

Attribute Description
id number readonly

Unique identifier of the line item.

product_id

Unique identifier of the product based on which line item is created. It is not available after creation.

value decimal

Value of one unit of the product. It is product’s price after applying markup.

variation decimal

Variation of the product’s price for this line item. Value of 5 means that 5% markup is added, -10 means there is a 10% discount.

currency string

Currency of value and price, specified in 3-character currency code (ISO4217) format.

quantity number

Quantity of the product included in this line item. Default value is 1.

price

Price of one unit of the product. Value is copied from the product.

name string readonly

Name of the product. Value is copied from the product.

sku string readonly

Stock Keeping Unit identification code. Value is copied from the product.

description string readonly

Description of the product. Value is copied from the product.

created_at string readonly

Date and time that the associated contact was created in UTC (ISO8601 format).

updated_at string readonly

Date and time of the last update on the associated contact in UTC (ISO8601 format).


Endpoints


Retrieve order's line items

Returns all line items associated to order.

Parameters

Attribute Description
page number optional

Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100.

e.g. ?per_page=20
sort_by string optional

A field to sort by. Default ordering is ascending. If you want to change the sort ordering to descending, append :desc to the field e.g. sort_by=value:desc.

Possible values:

  • id
  • value
  • quantity
  • updated_at
  • created_at
e.g. ?sort_by=created_at
ids string optional

Comma-separated list of line item IDs to be returned in a request.

e.g. ?ids=1,2,3
quantity number optional

Quantity of line item.

e.g. ?quantity=12
value decimal optional

Value of line item.

e.g. ?value=100.00

Create a line item

Adds a new line item to an existing order. Line items correspond to products in the catalog, so first you must create products. Because products allow defining different prices in different currencies, when creating a line item, the parameter currency is required.

If request does not specify value nor variation, we’ll assume variation is 0 (no markup), and set value to the price of the product. Price is picked based on the provided currency.

If either value or variation is provided, the other value is computed based on the price from the product. You can also specify both, in which case we do no calculations.

In all cases, we do check that the value is obtained from the price by applying the markup equal to variation. We also check that variation is within max_discount and max_markup, if these are set for the product.

Parameters

Attribute Description
product_id number required

Unique identifier of the product based on which line item is created.

e.g. "product_id": "2"
value decimal optional

Value of one unit of the product. It is product’s price after applying markup equal to variation.

e.g. "value": "3599.99"
variation decimal optional

Variation of the product’s price for this line item. Value of 5 means that 5% markup is added.

e.g. "variation": "0.00"
currency string required

Currency of the line item, specified in 3-character currency code (ISO4217) format. Used to choose price from product.

e.g. "currency": "EUR"
quantity number optional

Quantity of line item.

e.g. "quantity": "10"

Retrieve a single line item

Returns a single line item of an order, according to the unique line item ID provided.

Parameters

Attribute Description
order_id number required

Unique identifier of the order.

e.g. ?order_id=1
line_item_id number required

Unique identifier of the line item.

e.g. ?line_item_id=2

Remove a line item

Remove an order’s line item. This operation cannot be undone.

Parameters

Attribute Description
order_id number required

Unique identifier of the order.

e.g. ?order_id=1
line_item_id number required

Unique identifier of the line item.

e.g. ?line_item_id=2