Products
Build your product catalog with billing periods, trial settings, tax categories, and retry strategies for one-time and recurring charges
Products are the foundation of your billing catalog. They define what you sell, how customers are charged, and how billing behaves across one-time purchases and recurring subscriptions.
The product type drives billing behavior as it determines which flow applies, how taxes are calculated, and how failed payments are retried.
There are two product types:
- One-time
The customer is charged once. After payment, you deliver the product or grant access. No further charges apply. Use this type for goods or services sold as a single charge. - Recurring
The customer is billed at regular intervals for continued access to a product or service. Use this type for subscriptions, memberships, or any offering that requires ongoing access.
- In Billing 1.0, the product type determines the request model. Each product has a unique identifier,
product_id. Use the product-based paymentAPI v1 model for one-time products, such as direct purchases and upsells, and the subscriptionAPI v1 model for recurring products. - In Billing 2.0, products are added to an invoice, which is then paid.
You can assign a
If you are not yet using the Solidgate Tax solution, contact us to get started with it for your business.
Manage your products using the Solidgate API or Hub. You can create new products, update their settings, and archive ones that are no longer offered.
Create product
Creating a product requires a few key details about its type, pricing, and behavior.
Create productAPI v1 endpoint is used to create new products by providing the required details, such as name, status, type, and description. For recurring products, you must also provide the billing period and optionally specify trial settings and a suitable retry mode. Once created, the response includes the product’s unique identifier, creation date, and other relevant information.
When you create a product via API, it is locked for editing in the Solidgate Hub until a default price is added. To make the created product editable, set a default price using the create product priceAPI v1 operation.
To create a product and set its price
- Go to Billing > Products.
- Click on + Create product.
Complete the product settings by specifying:
- Product type (one-time or recurring)
- Product status and name
- Description
- Optionally, add a public description to appear on a customer’s bank statement
- Default price
- Settle interval
Configure taxes by specifying:
Tax category Tax behavior
- Click on Create product to save your new product.
While the product public description field is optional, providing it is highly recommended. The description is sent to banks and shown in customer bank statements, helping them understand who charged them and for what.
When using Solidgate
If you create a recurring product, set billing details, including price, currency, and billing period. The maximum length of the billing period is two years, regardless of whether you specify it in days, weeks, months, or years.
For Subscription 1.0, you can configure:
retry strategy smart retries - expired subscription setting to define the maximum number of billing periods before automatic cancellation with reason code
8.08
While for Subscription 2.0, you can set up
When you specify a settle interval for your product, you define the delay before transaction settlement. Solidgate might
Solidgate processes recurring payments in two steps auth + settle, and there are specific statuses that indicate the outcome:
auth_ok- funds are successfully reservedauth_failed- reservation of the funds failedsettle_ok- funds are successfully settledvoid_ok- operation of fund reservation is voided
Customers often request refunds within the first week after payment. Temporarily holding funds in the cardholder’s account helps prevent chargebacks by making transactions non-disputable. You can delay fund transfer by adjusting the time between authorization and settlement using the settle_interval parameter. Follow the settlement interval recommendations, because values depend on the card scheme and PSP.
If the customer is dissatisfied with the product or service, they have two options:
- contact their issuing bank to request the release of funds, after which the funds are released back to the cardholder
- contact the merchant support team to initiate a refund (
void) for the transaction
Edit product
Just as you create products, you can also edit them through the API or Hub.
Product type is set when you create the product and cannot be changed later.
Update productAPI v1 endpoint allows you to modify existing products. It requires specific details to be provided for the update process.
To edit a product and its price
- Go to Billing > Products.
- Find the product and click on it.
- On the product details page, click on Edit.
- Once you finish editing, click on Save changes.
What you can update depends on the product type, Billing version, and whether the product has associated subscriptions.
- For one-time products and recurring products without subscriptions, you can update all fields except the product type.
- For recurring products with subscriptions, you can update only the following fields, regardless of the subscription status:
- Product name
- Product description
- Public description
- Settle interval, which defines the time between settlement periods
- Retry mode (Billing 1.0 only)
- Tax category
- Tax behavior
- Currencies and locations: you can add new values, but you cannot remove existing ones
In Billing 1.0, products with active subscriptions do not support updates to the status, price, billing period, term length, or trial settings.
In Billing 2.0, retry mode and term length are not available at the product level.
Retrieve product details
To retrieve information about products, you can use the corresponding endpoints. They allow you to access details about a specific product by its ID or query multiple products with filtering options and pagination support.
Get a product by idAPI v1 endpoint retrieves a single product by its ID. The response returns product information that depends on the product type, including product ID, name, status, and more.
Get product listAPI v1 endpoint allows you to retrieve products by applying filters such as product ID, type, or status. Pagination is supported to manage the result sets. With the provided query parameters, you can specify the desired filters and control the number of items to return.
Archive product
Archiving products helps keep your product catalog organized and clutter-free, making it easier to manage and update active products. At the same time, it provides a way to keep detailed records of products or services that are no longer offered.
Archived products are not permanently deleted. Instead, they become historical data that you can find, view, and, if necessary, duplicate to create a new offer.
Archive productAPI v1 endpoint allows you to archive a product using its product_id.
To archive the product
- Go to Billing > Products.
- Find the product to archive.
- Click on the product to go to the product details page.
- In the top-right corner, click on the Archive️ button.
- Click on Confirm to save changes.
Once you archive a product, it is assigned the Archived️ status, which can be used for filtering purposes.
The archived product cannot be restored or added to new subscriptions. Any existing subscriptions with the archived product remain active until cancelled.