Products

The Products API provides a simple interface to manage the Product Catalog.

The catalog lists products available in your account. To add products to a deal, you should create an Order, then populate it with Line Items.

The API allows you to create, delete and update your products. You can also retrieve a single product as well as list of all products.

All users can read the Product Catalog, but it can be edited only by an account administrator. However, changes to products can be completely disabled in account's settings. When disabled, all data are preserved and only GET requests are allowed, even for administrators.

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

JSON format

Name	Read Only	Type	Description
`id`	true	number	Unique identifier of the product.
`name`	true	string	Name of the product.
`description`	false	string	Description of the product.
`sku`	false	string	Stock Keeping Unit identification code.
`active`	false	boolean	Indicator of whether the product is active. Line items cannot be created from inactive products.
`max_discount`	false	number	Maximum discount that can be applied to the product in percents.
`max_markup`	false	number	Maximum markup that can be applied to the product in percents.
`cost`	false	decimal	Cost of the product. Visible only to account administrators.
`cost_currency`	false	string	Currency of the product cost, specified in 3-character currency code (ISO4217) format. Visible only to account administrators.
`prices`	true	array	Array specifying products prices in different currencies.
`created_at`	true	string	Date and time that the product was created in UTC (ISO8601 format).
`updated_at`	true	string	Date and time of the last update on the product in UTC (ISO8601 format).

Retrieve all products

GET /v2/products

Returns all products from the catalog according to the parameters provided.

Parameters

Name	Required	Type	In	Description
`page`	optional	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. Maximum is `500`. Defaults to `25`.
`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`, `updated_at`, `created_at`
`ids`	false	string	Query	Comma-separated list of product IDs to be returned in a request.
`name`	false	string	Query	Name of the product.
`sku`	false	string	Query	SKU of the product.
`active`	false	boolean	Query	Indicator of whether or not the product is active.

Allowed for

Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/products \-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",        "active": true,        "prices": [          {            "amount": "1599.99",            "currency": "USD"          },          {            "amount": "3599.99",            "currency": "PLN"          }        ],        "cost": "999.99",        "cost_currency": "USD",        "max_discount": 15,        "max_markup": null,        "created_at": "2014-08-27T16:32:56Z",        "updated_at": "2014-08-27T17:32:56Z"      },      "meta": {        "type": "product"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/products?page=1&per_page=25"    }  }}

Create a product

POST /v2/products

Create a new product.

Products can be created only by an account administrator.

Parameters

Name	Required	Type	In	Description
`name`	true	string	Body	e.g. `Enterprise Plan`
`sku`	false	string	Body	e.g. `enterprise-plan`
`description`	false	string	Body	Description of the product.
`active`	false	boolean	Body	Whether the product is active. Defaults to true.
`cost`	false	number	Body	e.g. `1000`
`cost_currency`	false	string	Body	e.g. `EUR`
`max_discount`	false	number	Body	Maximum discount on product. Accepts `0`-`100` (inclusive). Defaults to `0`.
`max_markup`	false	number	Body	Maximum markup on product. Minimum is `0`. Defaults to `0`.
`prices`	true	array	Body	e.g. `[{"amount": "1599.99", "currency": "USD"}, {"amount": "3599.99", "currency": "PLN"}]`

Allowed for

Admins

Using cURL

curl -v -X POST https://api.getbase.com/v2/products \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "active": true,    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "cost": "1599.99",    "cost_currency": "USD",    "max_discount": 15  },  "meta": {    "type": "product"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": true,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Retrieve a single product

GET /v2/products/:id

Returns a single product, according to the unique product ID provided. If the specified product does not exist, the request will return an error.

Parameters

Name	Required	Type	In	Description
`id`	true	number	Query	Unique identifier for the product.

Allowed for

Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/products/1 \-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,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": true,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Update a product

PUT /v2/products/:id

Updates product information. If the specified product does not exist, the request will return an error.

Products can be modified only by an account administrator.

In order to modify prices used on a record, you need to supply the entire set. prices are replaced every time they are used in a request.

Parameters

Name	Required	Type	In	Description
`id`	true	number	Query	Unique identifier for the product.
`name`	false	string	Body	Name of the product.
`description`	false	string	Body	Description of the product.
`sku`	false	string	Body	Stock Keeping Unit identification code.
`active`	false	boolean	Body	Indicator of whether or not the product can be used in new line items.
`max_discount`	false	number	Body	Maximum discount that can be applied to the product in percents.
`max_markup`	false	number	Body	Maximum markup that can be applied to the product in percents.
`cost`	false	decimal	Body	Cost of the product.
`cost_currency`	false	string	Body	Currency of the product cost, specified in 3-character currency code (ISO4217) format.
`prices`	false	array	Body	Array specifying products prices in different currencies. e.g. `[{"currency": "USD", "amount": "1599.99"}, {"currency": "PLN", "amount": "3599.99"}]`

Allowed for

Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/products/1 \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "active": false  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "updated_at": "2014-08-27T16:32:56Z",    "created_at": "2014-08-27T16:32:56Z",    "active": false,    "name": "Enterprise Plan",    "sku": "enterprise-plan",    "description": "Includes more storage options",    "prices": [      {        "amount": "1599.99",        "currency": "USD"      },      {        "amount": "3599.99",        "currency": "PLN"      }    ],    "max_discount": 15,    "max_markup": null,    "cost": "1599.99",    "cost_currency": "USD"  },  "meta": {    "type": "product"  }}

Delete a product

DELETE /v2/products/:id

Delete an existing product from the catalog. Existing orders and line items are not affected. If the specified product does not exist, the request will return an error. This operation cannot be undone.

Products can be removed only by an account administrator.

Name	Required	Type	In	Description
`id`	true	number	Query	Unique identifier for the product.

Allowed for

Agents

Using cURL

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

Example response

HTTP/1.1 204 No Content

Authentication

Sync API

Search API

Firehose API

Core APIs

Apps

Products

JSON format

Retrieve all products

Parameters

Allowed for

Using cURL

Example response

Create a product

Parameters

Allowed for

Using cURL

Example response

Retrieve a single product

Parameters

Allowed for

Using cURL

Example response

Update a product

Parameters

Allowed for

Using cURL

Example response

Delete a product

Allowed for

Using cURL

Example response