Products
The Product object
Properties
- Name
id
- Type
- string
- Description
A unique identifier for the object.
- Name
name
- Type
- string
- Description
The name of your product. Displayed to customers. Max length (500).
- Name
description
- Type
- string
- Description
Describes your product to your customers. Max length (500).
- Name
images
- Type
- array
- Description
Up to six URL links to display images of your product displayed to your customers.
- Name
tags
- Type
- array
- Description
Labels and categorizes your products for querying and accounting purposes.
- They will also appear in your Dashboard >> Products
- Name
prices
- Type
- string array
- Description
List of
price
ids that define how much your product can cost. The selected price for a given product and payment method is defined by theprice
id that is passed to the lineItems field of a payment method.- Empty if you haven't yet pointed a price to a product.
- Will automatically update as prices get pointed to products.
- Name
meta
- Type
- object
- Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.
- Name
updated
- Type
- string
- Description
Datetime for when the product was last updated.
- Name
created
- Type
- string
- Description
Datetime for when the product was created.
Product Object
{
"id": "product_08092359305e4773b93f741fa69175d4",
"name": "Example product",
"description": "An example product for receiving payments.",
"images": [
"https://example.com/image.png",
"https://example.com/image2.png"
],
"tags": ["Example", "Product"],
"meta": { "type": "tier 3" },
"prices": ["price_6e65113b72e74b349222da1532f2e4ce"],
"updated": "2024-08-10T23:23:01.252Z",
"created": "2024-08-10T23:23:01.252Z"
}
Create a product
Creates a new product
object.
Parameters
- Name
name
- Type
- string
- Description
The name of your product. Displayed to customers. Max length (500).
- Name
description
- Type
- string
- Description
Describes your product to your customers. Max length (500).
- Name
images
- Type
- string array
- Description
Up to six URL links to display images of your product displayed to your customers.
- Name
tags
- Type
- string array
- Description
Labels and categorizes your products for querying and accounting purposes.
- They will also appear in your Dashboard >> Products
- Name
meta
- Type
- object
- Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.
- Name
prices
- Type
- string array
- Description
List of
price
ids. Defines how much your product can cost. The selected price for a given product and payment method is defined by theprice
id that is passed to the lineItems field of a payment method.- Empty if you haven't yet pointed a price to a product.
- Will automatically update as prices get pointed to products.
Request
curl https://api.spherepay.co/v1/product \
-H "Authorization: Bearer secret_72c3342954dd4825ad9c2eeb01890ca9" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"Example product\",
\"description\": \"An example product for receiving payments.\",
\"images\": [
\"https://example.com/image.png\",
\"https://example.com/image2.png\"
],
\"tags\": [
\"Example\",
\"Product\"
],
\"meta\": {
\"type\": \"tier 3\"
},
\"prices\": [
\"price_6e65113b72e74b349222da1532f2e4ce\"
]
}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"product": {
"id": "product_08092359305e4773b93f741fa69175d4",
"name": "Example product",
"description": "An example product for receiving payments.",
"images": [
"https://example.com/image.png",
"https://example.com/image2.png"
],
"tags": ["Example", "Product"],
"meta": { "type": "tier 3" },
"prices": ["price_6e65113b72e74b349222da1532f2e4ce"],
"updated": "2024-08-10T23:23:01.252Z",
"created": "2024-08-10T23:23:01.252Z"
}
},
"ts": "2024-08-10T23:23:01.264Z",
"request": "request_2902e67cd38d40cda95efd89a38c8ec7"
}
Retrieve a product
Retrieves a product
object by id
.
Request
curl -G https://api.spherepay.co/v1/product/product_08092359305e4773b93f741fa69175d4 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"product": {
"id": "product_08092359305e4773b93f741fa69175d4",
"name": "Example product",
"description": "An example product for receiving payments.",
"images": [
"https://example.com/image.png",
"https://example.com/image2.png"
],
"tags": ["Example", "Product"],
"meta": { "type": "tier 3" },
"prices": ["price_6e65113b72e74b349222da1532f2e4ce"],
"updated": "2024-08-10T23:23:01.252Z",
"created": "2024-08-10T23:23:01.252Z"
}
},
"ts": "2024-08-10T23:24:37.692Z",
"request": "request_e7c60a627d974f22a9408e66728cffaa"
}
Update a product
Updates a product
object with values passed in. Any parameters not provided are left unchanged.
Parameters
- Name
name
- Type
- string
- Description
The name of your product. Displayed to customers. Max length (500).
- Name
description
- Type
- string
- Description
Describes your product to your customers. Max length (500).
- Name
images
- Type
- string array
- Description
Up to six URL links to display images of your product displayed to your customers.
- Name
tags
- Type
- string array
- Description
Labels and categorizes your products for querying and accounting purposes.
- They will also appear in your Dashboard >> Products
- Name
meta
- Type
- object
- Description
Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.
- Name
prices
- Type
- string array
- Description
List of
price
ids. Defines how much your product can cost. The selected price for a given product and payment method is defined by theprice
id that is passed to the lineItems field of a payment method.- Empty if you haven't yet pointed a price to a product.
- Will automatically update as prices get pointed to products.
Request
curl https://api.spherepay.co/v1/product/product_08092359305e4773b93f741fa69175d4 \
-H "Authorization: Bearer secret_72c3342954dd4825ad9c2eeb01890ca9" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"New name\",
\"description\": \"New name same product.\"
}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"product": {
"id": "product_08092359305e4773b93f741fa69175d4",
"name": "New name",
"description": "New name same product.",
"images": [
"https://example.com/image.png",
"https://example.com/image2.png"
],
"tags": ["Example", "Product"],
"meta": { "type": "tier 3" },
"prices": ["price_6e65113b72e74b349222da1532f2e4ce"],
"updated": "2024-08-10T23:26:42.076Z",
"created": "2024-08-10T23:23:01.252Z"
}
},
"ts": "2024-08-10T23:26:42.093Z",
"request": "request_55ba5d9e769f4edaa3c629915a829562"
}
Delete a product
Deletes a product
object by id
. Deleting a product
also deletes its linked price
s.
Request
curl -X DELETE https://api.spherepay.co/v1/product/product_2803f2b29cd441b397c4fe7e75de73f5 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"product": {
"id": "product_08092359305e4773b93f741fa69175d4",
"name": "New name",
"description": "New name same product.",
"images": [
"https://example.com/image.png",
"https://example.com/image2.png"
],
"tags": ["Example", "Product"],
"meta": { "type": "tier 3" },
"prices": ["price_6e65113b72e74b349222da1532f2e4ce"],
"updated": "2024-08-10T23:28:18.664Z",
"created": "2024-08-10T23:23:01.252Z"
}
},
"ts": "2024-08-10T23:28:18.676Z",
"request": "request_9d8bff5f7fde4730b690d117a29ea8f1"
}
List all products
Returns a list of product
objects, sorted by newest creation date first.
Parameters
- Name
startDate
- Type
- string
- Description
The start Datetime that objects will begin to be pulled from.
- Name
endDate
- Type
- string
- Description
The end Datetime that objects will be fetched until.
- Name
limit
- Type
- integer
- Description
The maximum number of objects to pull. Defaults to 25, maximum is 200.
- Name
sort
- Type
- string
- Description
Sort data by field.
- Name
direction
- Type
- enum
- Description
The direction that payments will be sorted in. Either
ASC
orDESC
.
Request
curl -G https://api.spherepay.co/v1/product \
-H "Authorization: Bearer {token}" \
-d limit=2
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"products": [
{
"id": "product_be3dd81817dd4f6781c6e9422b57a0e5",
"name": "Empty product",
"description": "",
"images": [],
"tags": [],
"meta": {},
"prices": [],
"updated": "2024-08-10T23:20:22.499Z",
"created": "2024-08-10T23:20:22.499Z"
},
{
"id": "product_204be4d4ceaa441eaa3f5f460c1daa83",
// ...
}
]
},
"ts": "2024-08-10T23:35:10.878Z",
"request": "request_29742bce3a524a2ab0e0d490e90a44d3"
}