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.

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-8
Content-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-8
Content-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-8
Content-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-8
Content-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

---