Orders

Order allow the customer to 'spend' their collected money on either a Gift card, or another product you offer. On this page, we'll dive into the order endpoints you can use to manage orders programmatically. We'll look at how to query, create, and update orders.

The order model

The order model contains all the information about your orders, including the items, amount and customer.

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 order.
Name
amount
Type
integer
Description
The total charged for the order
Name
created_at
Type
timestamp
Description
Timestamp of when the order was created.
Name
pot
Type
string
Description
The unique identifier of the pot that payment is taken from
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
status
Type
enum
Description
The status of the order. The statuses are new, processing, complete, failed.
Name
currency
Type
string
Description
The currency of the order.
Name
price
Type
hash
Description
Details of the pricing for the order
Name
price.sub_total
Type
integer
Description
The sub total of the order
Name
price.shipping
Type
integer
Description
The cost of shipping for the order
Name
price.tax
Type
integer
Description
The amount of tax applied to the order
Name
price.total
Type
integer
Description
The total amount charged on the order including sub total, tax and shipping
Name
line_items
Type
array
Description
An array of line items making up the order
Name
line_items.product
Type
string
Description
The unique identifier of the product
Name
line_items.qty
Type
integer
Description
The number of items purchased
Name
line_items.unit_price
Type
integer
Description
The price for an individual unit
Name
line_items.tax
Type
integer
Description
The amount of tax for the item
Name
line_items.total
Type
integer
Description
The total price for the item
Name
shipping
Type
hash
Description
Details of shipping. This can either be physical postal shipping or digital delivery
Name
shipping.method
Type
enum
Description
The type of delivery method used, can be either postal or digital.
Name
shipping.address_line_1
Type
string
Description
The first line of the address to ship to.
Name
shipping.address_line_2
Type
string
Description
The second line of the address to ship to.
Name
shipping.city
Type
string
Description
The city of the address to ship to.
Name
shipping.state
Type
string
Description
The stae or county of the address to ship to.
Name
shipping.country
Type
string
Description
The countryof the address to ship to.
Name
shipping.postal_code
Type
string
Description
The postal code of the address to ship to.
Name
shipping.email
Type
string
Description
The email address to send the order to.
Name
expected_arrival
Type
timestamp
Description
Timestamp of when the order will arrive.
Name
failure_details
Type
hash
Description
Details on why the order failed
Name
failure_details.code
Type
string
Description
Order failure code.
Name
failure_details.message
Type
string
Description
An explanation on why the order failed.

GET/v1/orders

List all orders

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

Request

GET

/v1/orders

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "amount": 10000,
        "metadata": {},
        "status": "new" ,
        "currency": "GBP",
        "price" : {
            "sub_total": 10000,
            "shipping": 0,
            "tax": 0,
            "total": 10000
        },
        "line_items":[
            {
                "product": "ctv-jl-01",
                "qty": 1,
                "unit_price": 10000,
                "tax": 0,
                "total": 10000
            }    
        ],
        "shipping": {
            "method":"digital" ,
            "address_line_1": null,
            "address_line_2":null,
            "city": null,
            "state": null,
            "country": null,
            "postal_code": null,
            "email": "johnsmith@example.com"
        },
        "expected_arrival": 692234200,
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

GET/v1/orders/:id

Retrieve an order

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

Request

GET

/v1/orders/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,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "amount": 10000,
        "metadata": {},
        "status": "new" ,
        "currency": "GBP",
        "price" : {
            "sub_total": 10000,
            "shipping": 0,
            "tax": 0,
            "total": 10000
        },
        "line_items":[
            {
                "product": "ctv-jl-01",
                "qty": 1,
                "unit_price": 10000,
                "tax": 0,
                "total": 10000
            }    
        ],
        "shipping": {
            "method":"digital" ,
            "address_line_1": null,
            "address_line_2":null,
            "city": null,
            "state": null,
            "country": null,
            "postal_code": null,
            "email": "johnsmith@example.com"
        },
        "expected_arrival": 692234200,
}

POST/v1/orders

Create an order

This endpoint allows you to create a new order.

Required attributes

Name
pot
Type
string
Description
The unique identifier of the pot that the order corresponds to.
Name
line_items
Type
array
Description
An array of line items making up the order
Name
line_items.product
Type
string
Description
The unique identifier of the product
Name
line_items.qty
Type
integer
Description
The number of items purchased
Name
line_items.unit_price
Type
integer
Description
The price for an individual unit
Name
line_items.tax
Type
integer
Description
The amount of tax for the item
Name
line_items.total
Type
integer
Description
The total price for the item
Name
shipping
Type
hash
Description
Details of shipping. This can either be physical postal shipping or digital delivery
Name
shipping.method
Type
enum
Description
The type of delivery method used, can be either postal or digital.
Name
shipping.email
Type
string
Description
The email address to send the order to.

Optional attributes

Name
shipping.address_line_1
Type
string
Description
The first line of the address to ship to.
Name
shipping.address_line_2
Type
string
Description
The second line of the address to ship to.
Name
shipping.city
Type
string
Description
The city of the address to ship to.
Name
shipping.state
Type
string
Description
The stae or county of the address to ship to.
Name
shipping.country
Type
string
Description
The countryof the address to ship to.
Name
shipping.postal_code
Type
string
Description
The postal code of the address to ship to.

Request

POST

/v1/orders

curl -X POST https://api.collctiv.com/v1/orders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  '{"pot":"d4748db4-7863-4fa0-9a77-3cd329d5e652", line_items: [{"product":"ctv-jl-01", "qty":1, "unit_price" : 10000, "tax": 0, "total": 10000}], "shipping": {"method":"digital", "email": "janesmith@example.com"}}'

Response

{
  "has_more": false,
  "data": [
    {
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "amount": 10000,
        "metadata": {},
        "status": "new" ,
        "currency": "GBP",
        "price" : {
            "sub_total": 10000,
            "shipping": 0,
            "tax": 0,
            "total": 10000
        },
        "line_items":[
            {
                "product": "ctv-jl-01",
                "qty": 1,
                "unit_price": 10000,
                "tax": 0,
                "total": 10000
            }    
        ],
        "shipping": {
            "method":"digital" ,
            "address_line_1": null,
            "address_line_2":null,
            "city": null,
            "state": null,
            "country": null,
            "postal_code": null,
            "email": "janesmith@example.com"
        },
        "expected_arrival": 692234200,
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

PATCH/v1/orders

Update an order

This endpoint allows you to update an order.

Required attributes

Name
status
Type
enum
Description
The status of the order. The statuses are new, processing, complete, failed.

Request

PATCH

/v1/orders/:id

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "amount": 10000,
        "metadata": {},
        "status": "complete" ,
        "currency": "GBP",
        "price" : {
            "sub_total": 10000,
            "shipping": 0,
            "tax": 0,
            "total": 10000
        },
        "line_items":[
            {
                "product": "ctv-jl-01",
                "variant": "def023",
                "qty": 1,
                "unit_price": 10000,
                "tax": 0,
                "total": 10000
            }    
        ],
        "shipping": {
            "method":"digital" ,
            "address_line_1": null,
            "address_line_2":null,
            "city": null,
            "state": null,
            "country": null,
            "postal_code": null,
            "email": "johnsmith@example.com"
        },
        "expected_arrival": 692234200,
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}