API Endpoints

Products are the goods or services that you sell.

To get started, you will need to create a product.

The product object

Let's take a look at a full product object:

{
    "id": "product_94373caad0004e3e96c9e3b23d0c96c0",
    "active": "true",
    "created": "2023-07-14T22:35:47.118Z",
    "description": "This product encodes your billing scheme and can be attached to products.",
    "images": [
      "http://localhost:8080/img_0.png",
      "http://localhost:8080/img_1.png",
      "http://localhost:8080/img_2.png"
    ],
    "maxSupply": "10",
    "meta": {
    	"uuid": "<your_uuid>",
    },
    "name": "Example Product",
    "prices": [
        {
          .....
        }
    ],
    "tags": [
      "your_tag",
      "production"
    ],
    "updated": "2023-07-14T22:35:47.118Z",
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

active: boolean Denotes whether your product is usable in payment methods.

  • If a product is inactive, then attempts to include this product in a new payment method will fail.

created: string datetime for when the product was created.

description: string Describes your product to your customers. Max length (500).

images: string[] Up to six URL links to display images of your product to your customers.

maxSupply: number The maximum number of times that your product can be purchased.

  • Subsequent attempts to purchase will fail and return an API error.

meta: object 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: string The name of your product. Displayed to customers. Max length (500).

prices: price[] List of prices that define how much your product can cost. Relevant because oftentimes your prices will change, or you will want to offer the same product at different prices for different geographies, customer segments, or time periods. 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.

tags: string[] Labels and categorizes your products for querying and accounting purposes.

updated: string datetime for when the product was last updated.


Now that we've dove deep into the object definition, try creating a product yourself!