Products

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

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