Pots

Pots are central to the Collctiv platform. For your a customer to receive payments you must create a Pot. The Pot will contain all of the payments received, customers who have contributed and the current balance. On this page, we'll dive into the different pot endpoints you can use to manage pots programmatically. We'll look at how to query, create, and update pots.

The pot model

The pot model contains all the information about your pots, including who has contributed to the pot and the current balance.

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 pot.
Name
name
Type
string
Description
The name for the pot.
Name
created_at
Type
timestamp
Description
Timestamp of when the pot was created.
Name
balance
Type
integer
Description
The current balance of the pot.
Name
currency
Type
enum
Description
The currency that the pot will receive payments in. Can be either GBP or USD.
Name
volume
Type
integer
Description
The total amount of funds received in to the pot over it's life time.
Name
status
Type
enum
Description
The status of the pot, either open or closed.
Name
customer
Type
string
Description
The unique identifier of the customer that owns the pot.
Name
settings
Type
hash
Description
Detail about any pot specific settings such as whether notes are allowed on payments
Name
settings.contribution_notes_enabled
Type
boolean
Description
Allows the person who is paying into a pot to leave a note.
Name
settings.display_notes
Type
boolean
Description
Display the notes received on the hosted checkout page.
Name
requested_amount
Type
hash
Description
Details about the amount requested to be paid into the pot. This can be a fixed amount or this can be changed byy the customer during the payment.
Name
requested_amount.amount
Type
integer
Description
The amount requested to be contributed.
Name
requested_amount.type
Type
enum
Description
Is the amount to contribute fixed or open value. Use the enums open_value or fixed
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
redirect_url
Type
string
Description
The URL to return the customer to after payment has successfully completed.

GET/v1/pots

List all pots

This endpoint allows you to retrieve a paginated list of all your pots. By default, a maximum of ten pots 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.
Name
customer
Type
string
Description
The unique identifier of the customer that you wish to retrieve pots for.

Request

GET

/v1/pots

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": "dee11d4e-63c6-4d90-983c-5c9f1e79e96c",
      "name": "My Wedding Pot",
      "created_at": 692233200,
      "balance": 10000,
      "volume": 10000,
      "currency": "GBP",
      "status": "open",
      "customer": "2b2423401-f2fb-4355-8cff-4456c88a962",
      "settings": {
        "contribution_notes_enabled": true,
        "display_notes": false
      },
      "requested_amount": {
        "amount": 1000,
        "type": "open_value"
      },
      "metadata": {},
      "redirect_url":"https://mycompany.com/success"
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

POST/v1/pots

Create a pot

This endpoint allows you to create a new pot.

Required attributes

Name
name
Type
string
Description
The name for the pot.
Name
customer
Type
string
Description
The unique identifier of the customer that owns the pot.
Name
currency
Type
enum
Description
The currency that the pot will receive payments in. Can be either GBP or USD.
Name
redirect_url
Type
string
Description
The URL to return the customer to after payment has successfully completed.

Optional attributes

Name
settings
Type
hash
Description
Detail about any pot specific settings such as whether notes are allowed on payments
Name
settings.contribution_notes_enabled
Type
boolean
Description
Allows the person who is paying into a pot to leave a note.
Name
settings.display_notes
Type
boolean
Description
Display the notes received on the hosted checkout page.
Name
requested_amount
Type
hash
Description
Details about the amount requested to be paid into the pot. This can be a fixed amount or this can be changed byy the customer during the payment.
Name
requested_amount.amount
Type
integer
Description
The amount requested to be contributed.
Name
requested_amount.static
Type
boolean
Description
Is the amount to contribute fixed.
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.

Request

POST

/v1/pots

curl -X POST https://api.collctiv.com/v1/pots \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  '{"name":"My Wedding Pot", "customer":"2b2423401-f2fb-4355-8cff-4456c88a962"}'

Response

{
    "id": "dee11d4e-63c6-4d90-983c-5c9f1e79e96c",
      "name": "My Wedding Pot",
      "created_at": 692233200,
      "balance": 0,
      "volume": 0,
      "currency": "GBP",
      "status": "open",
      "customer": "2b2423401-f2fb-4355-8cff-4456c88a962",
      "settings": {
        "contribution_notes_enabled": true,
        "display_notes": false
      },
      "requested_amount": {
        "amount": 1000,
        "type": "open_value"
      },
      "metadata": {},
      "redirect_url":"https://mycompany.com/success"
}

GET/v1/pots/:id

Retrieve a pot

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

Request

GET

/v1/pots/ee11d4e-63c6-4d90-983c-5c9f1e79e96c

curl https://api.collctiv.com/v1/pots/ee11d4e-63c6-4d90-983c-5c9f1e79e96c \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "dee11d4e-63c6-4d90-983c-5c9f1e79e96c",
      "name": "My Wedding Pot",
      "created_at": 692233200,
      "balance": 10000,
      "volume": 10000,
      "status": "open",
      "currency": "GBP",
      "customer": "2b2423401-f2fb-4355-8cff-4456c88a962",
      "settings": {
        "contribution_notes_enabled": true,
        "display_notes": false
      },
      "requested_amount": {
        "amount": 1000,
        "type": "open_value"
      },
      "metadata": {},
      "redirect_url":"https://mycompany.com/success"
}

PATCH/v1/pots/:id

Update a pot

This endpoint allows you to perform an update on a pot. Examples of updates are changing the name, and metadata.

Optional attributes

Name
name
Type
string
Description
The name for the pot.
Name
settings
Type
hash
Description
Detail about any pot specific settings such as whether notes are allowed on payments
Name
settings.contribution_notes_enabled
Type
boolean
Description
Allows the person who is paying into a pot to leave a note.
Name
settings.display_notes
Type
boolean
Description
Display the notes received on the hosted checkout page.
Name
requested_amount
Type
hash
Description
Details about the amount requested to be paid into the pot. This can be a fixed amount or this can be changed byy the customer during the payment.
Name
requested_amount.amount
Type
integer
Description
The amount requested to be contributed.
Name
requested_amount.static
Type
boolean
Description
Is the amount to contribute fixed.
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.

Request

PATCH

/v1/pots/dee11d4e-63c6-4d90-983c-5c9f1e79e96c

curl -X PATCH https://api.collctiv.com/v1/pots/dee11d4e-63c6-4d90-983c-5c9f1e79e96c \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Wedding Pot!"}'

Response

{
  "id": "dee11d4e-63c6-4d90-983c-5c9f1e79e96c",
      "name": "My Wedding Pot!",
      "created_at": 692233200,
      "balance": 10000,
      "volume": 10000,
      "status": "open",
      "currency": "GBP",
      "customer": "2b2423401-f2fb-4355-8cff-4456c88a962",
      "settings": {
        "contribution_notes_enabled": true,
        "display_notes": false
      },
      "requested_amount": {
        "amount": 1000,
        "type": "open_value"
      },
      "metadata": {},
      "redirect_url":"https://mycompany.com/success"
},