Products

Products can be purchased using the funds collected in a pot. They are added to orders to fulfill the purchase. On this page, we'll dive into the order endpoints you can use to manage products programmatically. We'll look at how to query, create, and update products.

The product model

The product model contains all the information about your products.

Monetary values are in the smallest currency unit. e.g. £1.50 would be represented as 150.

Properties

Name
id
Type
string
Description
Unique identifier for the product.
Name
created_at
Type
timestamp
Description
Timestamp of when the product was created.
Name
metadata
Type
hash
Description
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Name
active
Type
boolean
Description
Whether the product is currently available for purchase.
Name
name
Type
string
Description
The product’s name, meant to be displayable to the customer.
Name
description
Type
string
Description
The product’s description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
Name
vendor
Type
string
Description
The provider of the product, this will either be your company or collctiv.
Name
images
Type
array
Description
A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
Name
price
Type
hash
Description
Details of the price of the object.
Name
price.type
Type
enum
Description
Determines whether the product is open value, such as a gift card or fixed price, such as a t-shirt. Values can either be open_value or fixed.
Name
price.start_price
Type
integer
Description
The price that the product starts at. If the product only has one price then set this as that price.
Name
price.end_price
Type
integer
Description
The price that the product end at. If the product only has one price then set this as that price.
Name
in_stock
Type
boolean
Description
Whether the product is in stock. Can be used to indicate to the customer whether the product is in stock.

GET/v1/products

List all products

This endpoint allows you to retrieve a paginated list of all your products. By default, a maximum of ten products are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of pots returned.
Name
page
Type
integer
Description
The page you wish to fetch.

Request

GET

/v1/products

curl -G https://api.collctiv.com/v1/products \
  -H "Authorization: Bearer {token}" \
  -d limit=3

Response

{
  "has_more": false,
  "data": [
    {
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "name": "John Lewis Gift Card",
        "description": "John Lewis & Partners began trading over 150 years ago in 1864 on London's Oxford Street, and is a leading omni-channel retailer in the UK with 34 John Lewis shops plus one outlet and online access through johnlewis.com. With an extensive range to choose from, John Lewis is an ideal destination for all your needs whether it be for a new sofa or for a gift for family or friend - there’s a huge range of brands available to suit your needs.",
        "vendor": "collctiv",
        "price": {
            "type": "open_value"
            "start_price": 500,
            "end_price": 25000
        },
        "in_stock": true,
        "active": true,
        "images": [ 
            "https://images.com/image.jpg"  
        ]
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

GET/v1/products/:id

Retrieve a product

This endpoint allows you to retrieve a product by providing the product id. Refer to the list at the top of this page to see which properties are included with product objects.

Request

GET

/v1/products/999fe8d5-1615-414b-83fc-2740b3c4a899

curl https://api.collctiv.com/v1/orders/999fe8d5-1615-414b-83fc-2740b3c4a899 \
  -H "Authorization: Bearer {token}"

Response

{
     "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "name": "John Lewis Gift Card",
        "description": "John Lewis & Partners began trading over 150 years ago in 1864 on London's Oxford Street, and is a leading omni-channel retailer in the UK with 34 John Lewis shops plus one outlet and online access through johnlewis.com. With an extensive range to choose from, John Lewis is an ideal destination for all your needs whether it be for a new sofa or for a gift for family or friend - there’s a huge range of brands available to suit your needs.",
        "vendor": "collctiv",
        "price": {
            "type": "open_value"
            "start_price": 500,
            "end_price": 25000
        },
        "in_stock": true,
        "active": true,
        "images": [ 
            "https://images.com/image.jpg"  
        ]
}

POST/v1/products

Create a product

This endpoint allows you to create a new product.

Required attributes

Name
name
Type
string
Description
The product’s name, meant to be displayable to the customer.
Name
vendor
Type
string
Description
The provider of the product, this will either be your company or collctiv.
Name
images
Type
array
Description
A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
Name
price
Type
hash
Description
Details of the price of the object.
Name
price.type
Type
enum
Description
Determines whether the product is open value, such as a gift card or fixed price, such as a t-shirt. Values can either be open_value or fixed.
Name
price.start_price
Type
integer
Description
The price that the product starts at. If the product only has one price then set this as that price.
Name
price.end_price
Type
integer
Description
The price that the product end at. If the product only has one price then set this as that price.
Name
in_stock
Type
boolean
Description
Whether the product is in stock. Can be used to indicate to the customer whether the product is in stock.

Optional attributes

Name
metadata
Type
hash
Description
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Name
active
Type
boolean
Description
Whether the product is currently available for purchase.
Name
description
Type
string
Description
The product’s description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.

Request

POST

/v1/products

curl -X POST https://api.collctiv.com/v1/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Lewis Gift Card", "vendor":"mycompany", "images": ["https://images.com/image.png"], "price": {"type":"open_value", "start_price": 500, "end_price": 25000}, "in_stock": true }'

Response

{
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "name": "John Lewis Gift Card",
        "description": "",
        "vendor": "collctiv",
        "price": {
            "type": "open_value",
            "start_price": 500,
            "end_price": 25000
        },
        "in_stock": true,
        "active": true,
        "images": [ 
            "https://images.com/image.jpg"  
        ]
}

PATCH/v1/product

Update a product

This endpoint allows you to update a product.

Optional attributes

Name
metadata
Type
hash
Description
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Name
active
Type
boolean
Description
Whether the product is currently available for purchase.
Name
description
Type
string
Description
The product’s description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
Name
name
Type
string
Description
The product’s name, meant to be displayable to the customer.
Name
images
Type
array
Description
A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
Name
price
Type
hash
Description
Details of the price of the object.
Name
price.type
Type
enum
Description
Determines whether the product is open value, such as a gift card or fixed price, such as a t-shirt. Values can either be open_value or fixed.
Name
price.start_price
Type
integer
Description
The price that the product starts at. If the product only has one price then set this as that price.
Name
price.end_price
Type
integer
Description
The price that the product end at. If the product only has one price then set this as that price.
Name
in_stock
Type
boolean
Description
Whether the product is in stock. Can be used to indicate to the customer whether the product is in stock.

Request

PATCH

/v1/products

curl -X PATCH https://api.collctiv.com/v1/products/999fe8d5-1615-414b-83fc-2740b3c4a899 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d {"name":"John Lewis"}

Response

{
  "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "name": "John Lewis",
        "description": "John Lewis & Partners began trading over 150 years ago in 1864 on London's Oxford Street, and is a leading omni-channel retailer in the UK with 34 John Lewis shops plus one outlet and online access through johnlewis.com. With an extensive range to choose from, John Lewis is an ideal destination for all your needs whether it be for a new sofa or for a gift for family or friend - there’s a huge range of brands available to suit your needs.",
        "vendor": "collctiv",
        "price": {
            "type": "open_value"
            "start_price": 500,
            "end_price": 25000
        },
        "in_stock": true,
        "active": true,
        "images": [ 
            "https://images.com/image.jpg"  
        ]
}