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.

JSON format

Name Read Only Type Description
id true number Unique identifier of the line item.
product_id true number Unique identifier of the product based on which line item is created. It is not available after creation.
value false decimal Value of one unit of the product. It is product's price after applying markup.
variation false 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 true string Currency of value and price, specified in 3-character currency code (ISO4217) format.
quantity false number Quantity of the product included in this line item. Default value is 1.
price true string Price of one unit of the product. Value is copied from the product.
name true string Name of the product. Value is copied from the product.
sku true string Stock Keeping Unit identification code. Value is copied from the product.
description true string Description of the product. Value is copied from the product.
created_at true string Date and time that the associated contact was created in UTC (ISO8601 format).
updated_at true string Date and time of the last update on the associated contact in UTC (ISO8601 format).

Retrieve order's line items

GET /v2/orders/:order_id/line_items

Returns all line items associated to order.

Parameters

Name Required Type In Description
page false number Query Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_page false number Query Number of records to return per page. Defaults to all records.
sort_by false string Query 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
ids false string Query Comma-separated list of line item IDs to be returned in a request.
quantity false number Query Quantity of line item.
value false decimal Query Value of line item.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/orders/:order_id/line_items \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 1,        "name": "Enterprise Plan",        "sku": "enterprise-plan",        "description": "Includes more storage options",        "value": "3599.99",        "variation": "0.00",        "price": "3599.99",        "currency": "USD",        "quantity": 10,        "created_at": "2014-08-27T16:32:56Z",        "updated_at": "2014-08-27T17:32:56Z"      },      "meta": {        "type": "line_item"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/orders/1/line_items?page=1&per_page=25"    }  }}

Create a line item

POST /v2/orders/:order_id/line_items

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

Name Required Type In Description
order_id true number Query Unique identifier for the order.
product_id true number Body Unique identifier for the product.
value false decimal Body Value of one unit of the product. It is product’s price after applying markup equal to variation.
variation false decimal Body Variation of the product's price for this line item. Value of 5 means that 5% markup is added.
currency true string Body Currency of the line item, specified in 3-character currency code (ISO4217) format. Used to choose price from product.
quantity false number Body Quantity of line item.

Allowed for

  • Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/orders/1/line_items \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "product_id": 1,    "value": "3599.99",    "currency": "USD",    "variation": "0.00",    "quantity": 10  },  "meta": {    "type": "line_item"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "value": "3599.99",    "variation": "0.00",    "price": "3599.99",    "currency": "USD",    "quantity": 10,    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2014-08-27T17:32:56Z"  },  "meta": {    "type": "line_item"  }}

Retrieve a single line item

GET /v2/orders/:order_id/line_items/:line_item_id

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

Parameters

Name Required Type In Description
order_id true number Query Unique identifier of the order.
line_item_id true number Query Unique identifier of the line item.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/orders/1/line_items/2 \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "value": "3599.99",    "variation": "0.00",    "price": "3599.99",    "currency": "USD",    "quantity": 10,    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2014-08-27T17:32:56Z"  },  "meta": {    "type": "line_item"  }}

Update order's line item

PUT /v2/orders/:order_id/line_items/:line_item_id

Updates a line item associated with the order.

Parameters

Name Required Type In Description
order_id true number Query Unique identifier for the order.
line_item_id true number Query Unique identifier for the line item.
value false decimal Body Value of one unit of the product, which is the product’s price after applying a markup equal to variation.
variation false decimal Body Variation of the product's price for this line item. For example, a value of 5 means that 5% markup is added.
currency true string Body Currency of the line item, specified in a three-character currency code (ISO4217) format. Used to choose price from product.
quantity false number Body Quantity of line item.

Allowed for

  • Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/orders/:order_id/line_items/:line_item_id \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-H "Content-Type: application/json" \-d '{  "data": {    "product_id": 1,    "value": "3599.99",    "currency": "USD",    "variation": "0.00",    "quantity": 10  },  "meta": {    "type": "line_item"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 1,        "name": "Enterprise Plan",        "sku": "enterprise-plan",        "description": "Includes more storage options",        "value": "3599.99",        "variation": "0.00",        "price": "3599.99",        "currency": "USD",        "quantity": 10,        "created_at": "2014-08-27T16:32:56Z",        "updated_at": "2014-08-27T17:32:56Z"      },      "meta": {        "type": "line_item"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/orders/1/line_items?page=1&per_page=25"    }  }}

Remove a line item

DELETE /v2/orders/:order_id/line_items/:line_item_id

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

Parameters

Name Required Type In Description
order_id true number Query Unique identifier of the order.
line_item_id true number Query Unique identifier of the line item.

Allowed for

  • Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/orders/1/line_items/2 \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content