Guides

Create product catalog

This tutorial walks you through the steps required to create a product catalog using the Subskribe API.

A product catalog contains products and plans associated with each product.

To create a product catalog using the Subskribe API:

  1. Create a product using the Create a product endpoint.
  2. Create one or more plans for the product using the Create a plan endpoint.

Step 1: Create a product

The following sections describe how to create a product using the Subskribe API.

Prerequisites for creating a product

To create a product, you'll need:

  • Your Subskribe API key

Constructing the request body

The Create a product endpoint requires two parameters in the request body: product name and product SKU (stock keeping unit).

In this example, we're creating a new product named AmazingCloud Platform with a SKU value of SKU-1001.

Required parameters

name
  • Type: string
    • Value: AmazingCloud Platform
    • Details: Unique name of the product.
sku
  • Type: string
    • Value: SKU-1001
    • Details: The stock keeping unit (SKU) for the product.

Optional parameters

We also include the following optional parameters to provide additional order details:

displayName
  • Type: string
    • Value: Your AmazingCloud
    • Details: This is the name of the product as it is shown to the customer.
description
  • Type: string
    • Value: An enterprise-grade cloud storage platform
    • Details: A detailed description of the product.

For a complete list of parameters, refer to the Create a product endpoint documentation.

Sample request

curl -X POST "https://api.app.subskribe.com/products" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AmazingCloud Platform",
    "sku": "SKU-1001",
    "displayName": "Your AmazingCloud",
    "description": "An enterprise-grade cloud storage platform"
}'

Examining the response

Upon successful creation, the API returns the product object containing details about the new product.

Key fields in the response include:

  • id: The unique identifier for the product. We'll use this ID to identify the product while adding plans and charges to it.
  • inUse: When set to false, this indicates that there are no plans currently associated with this product, and hence it's not in use.
{
    "id": "PROD-MK7F467",
    "entityIds": [
        "*"
    ],
    "name": "AmazingCloud Platform",
    "displayName": "Your AmazingCloud",
    "inUse": false,
    "description": "An enterprise-grade cloud storage platform",
    "sku": "SKU-1001",
    "productCategoryId": null,
    "productCategory": null,
    "updatedOn": 1759453812,
    "externalId": null,
    "eventObjectId": "PROD-MK7F467"
}

Step 2: Create plans

A plan is a collection of charges that dictates how a product is priced.

Prerequisites for creating a plan

To create a product, you'll need:

  • Your Subskribe API key
  • The ID of the product to which you're adding this plan. This is the id value returned as part of the success response from the Create a product endpoint.

Constructing the request body

In this example, we want to add two plans - one for a monthly subscription, and another for an annual subscription to the AmazingCloud Platform.

Required parameters

name
  • Type: string
    • Value: Monthly subscription
    • Details: Unique name of the plan.
status
  • Type: string, enum
    • Value: DRAFT. Supported values are DRAFT, ACTIVE, GRANDFATHERED, ARCHIVED and DEPRECATED.
    • Details: The status of the plan when it's created. Set the status to DRAFT when creating a new plan.
productId
  • Type: string
    • Value: PROD-MK7F467.
    • Details: ID of the product to which you're adding this plan. This is the id value returned as part of the success response from the Create a product endpoint.
charges
  • Type: object
  • Value:
  "charges": [
  {
      "name": "Monthly recurring", // Monthly subscription charge
      "displayName": "Monthly plan", // Name of the charge as shown to customers
      "amount": 1250, // The cost of the subscription
      "type": "RECURRING", // Type of charge enum value
      "chargeModel": "PER_UNIT", // Pricing model enum value
      "isRenewable": true, // Indicates if the charge is renewable
      "recurrence": {
          "cycle": "MONTH", // Enum value indicates that the charge repeats monthly
          "step": 1 // Indicates that the charge repeats once per cycle
      }
  }
]
  • Details: Array of charges in the plan. In this example we have one array object representing the monthly subscription charge.

Optional parameters

We also include the following optional parameters to provide additional order details:

displayName
  • Type: string
    • Value: Your AmazingCloud
    • Details: This is the name of the product as it is shown to the customer.
currency
  • Type: string
    • Value: USD
    • Details: The currency in which the plan's pricing is listed.

For a complete list of parameters, refer to the Create a product endpoint documentation.

Sample request

curl -X POST "https://api.app.subskribe.com/plans" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
   "name": "Monthly Subscription",
   "displayName": "Your AmazingCloud",
   "status": "DRAFT",
   "productId": "PROD-MK7F467",
   "currency": "USD",
   "charges": [
       {
           "name": "Monthly recurring",
           "displayName": "Monthly plan",
           "amount": 1250,
           "type": "RECURRING",
           "chargeModel": "PER_UNIT",
           "isRenewable": true,
           "recurrence": {
               "cycle": "MONTH",
               "step": 1
           }
       }
   ]
}
'

Examining the response

Upon successful creation, the API returns the product object containing details about the new product.

Key fields in the response include:

  • id: The unique identifier of the plan.
  • charges.id: The unique identifier of the charge.
{
    "id": "PLAN-3Y97D8J",
    "entityIds": [
        "*"
    ],
    "name": "Monthly Subscription",
    "displayName": "Your AmazingCloud",
    "description": null,
    "status": "DRAFT",
    "productId": "PROD-MK7F467",
    "charges": [
        {
            "id": "CHRG-Y0EYRVE",
            "name": "Monthly recurring",
            "displayName": "Monthly plan",
            "description": null,
            "taxRateId": null,
            "unitOfMeasureId": null,
            "isRenewable": true,
            "isCreditable": false,
            "isListPriceEditable": false,
            "minQuantity": null,
            "defaultQuantity": null,
            "maxQuantity": null,
            "externalId": null,
            "minAmount": null,
            "maxAmount": null,
            "recognitionRuleId": null,
            "erpId": null,
            "itemCode": null,
            "planId": "PLAN-3Y97D8J",
            "amount": 1.25E+3,
            "type": "RECURRING",
            "chargeModel": "PER_UNIT",
            "recurrence": {
                "cycle": "MONTH",
                "step": 1
            },
            "priceTiers": [],
            "isDrawdown": false,
            "minimumCommitBaseChargeId": null,
            "overageBaseChargeId": null,
            "isCustom": false,
            "percent": null,
            "percentDerivedFrom": null,
            "targetPlanIds": [],
            "ledgerAccountMapping": null,
            "durationInMonths": null,
            "isEventBased": false,
            "isDiscount": false,
            "rateCardId": null,
            "billingTerm": "UP_FRONT",
            "billingCycle": "DEFAULT",
            "shouldTrackArr": null,
            "customFields": {},
            "custom": false,
            "eventObjectId": "CHRG-Y0EYRVE",
            "drawdown": false,
            "eventBased": false,
            "creditable": false
        }
    ],
    "currency": "USD",
    "externalId": null,
    "templateIds": [],
    "replacementPlanIds": null,
    "customFields": {},
    "updatedOn": 1759519585,
    "eventObjectId": "PLAN-3Y97D8J"
}

Adding a second plan

Similarly to the monthly plan, we'll add another plan to create an annual subscription.

Sample request to add an annual subscription plan

curl -X POST "https://api.app.subskribe.com/plans" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
   "name": "Annual Subscription",
   "displayName": "Your AmazingCloud",
   "status": "DRAFT",
   "productId": "PROD-MK7F467",
   "currency": "USD",
   "charges": [
       {
           "name": "Annual recurring",
           "displayName": "Annual plan",
           "amount": 10000,
           "type": "RECURRING",
           "chargeModel": "PER_UNIT",
           "isRenewable": true,
           "recurrence": {
               "cycle": "YEAR",
               "step": 1
           }
       }
   ]
}
'

Sample response after an annual subscription plan

{
    "id": "PLAN-HH6KC45",
    "entityIds": [
        "*"
    ],
    "name": "Annual Subscription",
    "displayName": "Your AmazingCloud",
    "description": null,
    "status": "DRAFT",
    "productId": "PROD-MK7F467",
    "charges": [
        {
            "id": "CHRG-X8W0RMY",
            "name": "Annual recurring",
            "displayName": "Annual plan",
            "description": null,
            "taxRateId": null,
            "unitOfMeasureId": null,
            "isRenewable": true,
            "isCreditable": false,
            "isListPriceEditable": false,
            "minQuantity": null,
            "defaultQuantity": null,
            "maxQuantity": null,
            "externalId": null,
            "minAmount": null,
            "maxAmount": null,
            "recognitionRuleId": null,
            "erpId": null,
            "itemCode": null,
            "planId": "PLAN-HH6KC45",
            "amount": 1E+4,
            "type": "RECURRING",
            "chargeModel": "PER_UNIT",
            "recurrence": {
                "cycle": "YEAR",
                "step": 1
            },
            "priceTiers": [],
            "isDrawdown": false,
            "minimumCommitBaseChargeId": null,
            "overageBaseChargeId": null,
            "isCustom": false,
            "percent": null,
            "percentDerivedFrom": null,
            "targetPlanIds": [],
            "ledgerAccountMapping": null,
            "durationInMonths": null,
            "isEventBased": false,
            "isDiscount": false,
            "rateCardId": null,
            "billingTerm": "UP_FRONT",
            "billingCycle": "DEFAULT",
            "shouldTrackArr": null,
            "customFields": {},
            "custom": false,
            "eventObjectId": "CHRG-X8W0RMY",
            "drawdown": false,
            "eventBased": false,
            "creditable": false
        }
    ],
    "currency": "USD",
    "externalId": null,
    "templateIds": [],
    "replacementPlanIds": null,
    "customFields": {},
    "updatedOn": 1759520180,
    "eventObjectId": "PLAN-HH6KC45"
}

Best practices

  • Use the isDryRun=true query parameter when creating products or plans to test without persisting them.

Error handling

Error codeError detailsRecovery options
401 UnauthorizedInvalid API keyThe most likely cause is that your API key is missing or it has expired. Try again with valid API credentials.
400 Bad RequestMissing required fields or request contains invalid valuesSee the error response from the endpoint for recovery details that are specific to the cause of the error. This error may be caused due to one or more problems with the request body.

Updated 9 days ago

Did this page help you?