Products

Products are the goods or services that you sell.

Endpoints

POST

/v1/product

The Product object

Properties

Name
id
Type
string
Description
Unique identifier for the object. Auto-generated by Sphere upon creation.
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 the price 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"
}

POST/v1/product

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 the price 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

POST

/v1/product

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"
}

GET/v1/product/:id

Retrieve a product

Retrieves a product object by id.

Request

GET

/v1/product/:id

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"
}

POST/v1/product/:id

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 the price 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

POST

/v1/product/:id

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/v1/product/:id

Delete a product

Deletes a product object by id. Deleting a product also deletes its linked prices.

Request

DELETE

/v1/product/:id

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"
}

GET/v1/product

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 or DESC.

Request

GET

/v1/product

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"
}