Products

Products are the goods or services that you sell.

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.

  • 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.

  • 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.

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

Was this page helpful?