Products

At Zūm Rails one product can have one or more prices, these are called product prices and need to be informed at the moment of creating a product. Product prices can have different types of configurations such as Pricing Model and Frequency.

Pricing Models Types

TypeBehavior
StandardYou should select standard pricing if you want to charge your users a fixed price per unit.
PackageYou should select package pricing if you want to charge your users for a group of units. Say you charge $50 for every 10 units. If the user buys 15 units, he will be charged $100 by default.

Frequency Types

TypeBehavior
OneTimeIf this is a product which is available as a one time purchase by paying the full price right now, choose frequency “OneTime”.
RecurringIf this is a product which is available as a recurring subscription, choose frequency “Recurring".

Creating a new product#

{
"Name": "Test Product",
"Description": "Product Description",
"SecurityPassword": "your_password",
"ProductPrices": [
{
"ProductPriceType": "Standard",
"Price": 22.55,
"PerUnit": 0,
"Frequency": "OneTime",
"PlanName": null,
"PlanDescription": null,
"BillingPeriod": null,
"EnableSubscriptionEndDate": null,
"SubscriptionEndDate": null,
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0
}
]
}

Method: POST

Endpoint: {{env}}/api/product

Use this endpoint if you want to add a new product to your account.

Input parameters

ParameterTypeMandatoryDescription
NamestringyesProduct Name
DescriptionstringnoProduct Description
SecurityPasswordstringyesYour current password
Pricesyes
ProductPriceTypestringyesPrice Model
PricedecimalyesPrice value
PerUnitintyes (if ProductPriceType is Package)Package size
FrequencydecimalyesPrice frequency
PlanNamestringyes (if Frequency is recurring)Recurring plan name
PlanDescriptionstringnoPrice frequency
BillingPeriodstringyes (if Frequency is recurring)Billing Period Type
EnableSubscriptionEndDateboolnoEnable subscription end date
SubscriptionEndDatedateyes (if EnableSubscriptionEndDate is true)End date that makes subscription available
EnableFreeTrialboolnoEnable free trial feature
FreeTrialInDaysintyes (if EnableFreeTrial is true)Number of days for free trial
EnableSetupFeeboolnoEnable setup fee
SetupFeedecimalyes (if EnableSetupFee is true)Number of days for free trial

Billing Period Type

ParameterTypeDescription
MonthlystringSets a monthly recurrence
WeeklystringSets a weekly recurrence
BiweeklystringSets a biweeky recurrence
AnnuallystringSets an annual recurrence

Uploading a product picture#

{
"Bytes": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAUFBQUGBQYHBwYJCQgJCQ0MCwsMDRMODw4PDhMdEhUSEhUSHRofGRcZHxouJCAgJC41LSotNUA5OUBRTVFqao4BBQUFBQYFBgcHBgkJCAkJDQwLCwwNEw4PDg8OEx0SFRISFRIdGh8ZFxkfGi4kICAkLjUtKi01QDk5QFFNUWpqjv/CABEIBd0F3AMBIgACEQEDEQH/xAAdA...",
"Filename": "marketing-kit-launch-binders-com-open-49901SD.jpg",
"SecurityPassword": "your_password"
}

Method: PATCH

Endpoint: {{env}}/api/product/{{producId}}/uploadproductimage

Use this endpoint if you want to upload a new image to a product.

Input parameters

ParameterTypeMandatoryDescription
FilenamestringyesFiles name
SecurityPasswordstringyesYour password
BytesstringyesThe file's blob
info

To remove a image send a request with Filename and Bytes values has null

Update a product#

{
"Name": "Test",
"Description": "Teste",
"SecurityPassword": "!@#Change",
"ProductPrices": [
{
"Id": "68fe5724-7a8b-41d7-9e9c-350f15953d00",
"ProductPriceType": "Standard",
"Price": 123.25,
"PerUnit": 0,
"Frequency": "Recurring",
"PlanName": "Test Recurring",
"PlanDescription": "Test Description",
"BillingPeriod": "Annually",
"EnableSubscriptionEndDate": true,
"SubscriptionEndDate": "2022-02-26",
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0,
"SetToRemove": true
},
{
"ProductPriceType": "Standard",
"Price": 25.67,
"PerUnit": 0,
"Frequency": "Recurring",
"PlanName": "Test Recurring",
"PlanDescription": "Test Description",
"BillingPeriod": "Annually",
"EnableSubscriptionEndDate": true,
"SubscriptionEndDate": "2022-02-26",
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0
}
]
}

Method: PUT

Endpoint: {{env}}/api/product/{{product_id}}

Use this endpoint if you want to update a new product on your account.

Input parameters

ParameterTypeMandatoryDescription
NamestringyesProduct Name
DescriptionstringnoProduct Description
SecurityPasswordstringyesYour current password
Pricesyes
Idguidyes (only if you are editing)The Id for the product price
ProductPriceTypestringyesPrice Model
PricedecimalyesPrice value
PerUnitintyes (if ProductPriceType is Package)Package size
FrequencydecimalyesPrice frequency
PlanNamestringyes (if Frequency is recurring)Recurring plan name
PlanDescriptionstringnoPrice frequency
BillingPeriodstringyes (if Frequency is recurring)Billing Period Type
EnableSubscriptionEndDateboolnoEnable subscription end date
SubscriptionEndDatedateyes (if EnableSubscriptionEndDate is true)End date that makes subscription available
EnableFreeTrialboolnoEnable free trial feature
FreeTrialInDaysintyes (if EnableFreeTrial is true)Number of days for free trial
EnableSetupFeeboolnoEnable setup fee
SetupFeedecimalyes (if EnableSetupFee is true)Number of days for free trial
SetToRemoveboolyes (only if you are editing)This will remove the product price of the product if set to true

Get a specific product#

Use this endpoint if you want to get all the information for a specific product.

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"Id": "2ab8f5fa-02a7-4e91-a426-ef09adab3fc8",
"Name": "Test",
"Description": "Test",
"ProductStatus": "Active",
"ProductPrices": [
{
"Id": "037b8b2e-9cc0-4059-a246-f4c02e3564d4",
"product_id": "2ab8f5fa-02a7-4e91-a426-ef09adab3fc8",
"CreatedAt": "2022-02-11T17:25:26.970291",
"ProductPriceType": "Standard",
"ProductPriceStatus": "Active",
"Price": 25.67,
"PerUnit": 0,
"Frequency": "Recurring",
"PlanName": "Test Recurring",
"PlanDescription": "Test Description",
"BillingPeriod": "Annually",
"EnableSubscriptionEndDate": true,
"SubscriptionEndDate": "2022-02-26T03:00:00",
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0,
"Currency": "CAD",
"Product": {
"Id": "2ab8f5fa-02a7-4e91-a426-ef09adab3fc8",
"Name": "Test",
"Description": "Test",
"ProductStatus": "Active",
"CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035"
}
}
],
"ConnectUrl": "connect_url",
"CreatedAt": "2022-02-11T15:22:29.58586"
}
}

Method: GET

Endpoint: {{env}}/api/product/{product_id}

Response

ParameterTypeDescription
IdguidProduct id
NamestringProduct Name
DescriptionstringProduct Description
ProductStatusstringStatus for the product
ConnectUrlstringPublic url for access to this product
CreatedAtdateCreation date
ProductPrices
IdstringThe Id for the product price
ProductIdstringThe Id for the product on witch is related
CreatedAtdateCreation date
ProductPriceTypestringPrice Model
ProductPriceStatusstringStatus for the product price
PricedecimalPrice
PerUnitstringPackage size
FrequencystringPrice frequency
PlanNamestringPlan name
PlanDescriptionstringPlan description
BillingPeriodstringBilling Period Type
EnableSubscriptionEndDateboolEnable subscription end date
SubscriptionEndDatedateEnd date that makes subscription available
EnableFreeTrialboolEnable free trial feature
FreeTrialInDaysintNumber of days for free trial
EnableSetupFeeboolEnable setup fee
SetupFeedecimalNumber of days for free trial
CurrencystringCurrency set for the product price

Search a product#

This endpoint will return products based on the filter informed. Products are returned with pagination, which means that if you need to retrieve all products you need to call the same endpoint incrementing the CurrentPage.

{
"CreatedAt": "2022-02-07T03:00:00.000Z",
"CreatedAtOperator": "isInTheLast",
"ProductStatus": 0,
"GenericSearch": "Product",
"Pagination": {
"PageNumber": 1,
"ItemsPerPage": 7
}
}

Method: POST

Endpoint: {{env}}/api/product/filter

Response

Input parameters

ParameterTypeMandatoryDescription
GenericSearchstringnoFilter products by product name or product id
ProductStatusstringnoProduct status
CreatedAtdatetimenoCreate date
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
Paginationno
PageNumbernumbernoThe respective page, starting at 1

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of products
IdguidThe product Id
NamestringThe product name
DescriptionstringThe product description
ProductStatusstringThe status for the product
CreatedAtdateThe creation date for the product
ProductPricesList of Product Prices
IdguidThe product price Id
ProductIdguidThe Id for the product where this product price is used
CreatedAtdateThe creation date for the product price
ProductPriceTypestringThe pricing model for the price
ProductPriceStatusstringThe status for the product price
PricedecimalPrice
PerUnitstringPackage size
FrequencystringPrice frequency
PlanNamestringyes (if Frequency is recurring)
PlanDescriptionstringno
BillingPeriodstringyes (if Frequency is recurring)
EnableSubscriptionEndDateboolno
SubscriptionEndDatedateyes (if EnableSubscriptionEndDate is true)
EnableFreeTrialboolno
FreeTrialInDaysintyes (if EnableFreeTrial is true)
EnableSetupFeeboolno
SetupFeedecimalyes (if EnableSetupFee is true)
CurrencystringCurrency selected for the product price
ProductRelated product
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer
tip

If you need to search for a specific product, we recommend that you retrieve the product id and then use the GET specific product endpoint to retrieve the detailed information about the product.

Archive a product#

Use this endpoint if you want to archive a product. Once archived, the product will not be visible in any end user facing screens. If there are any active subscriptions or invoices they will remain until cancelled.

{
"statusCode": 200,
"message": "PATCH Request successful.",
"isError": false,
"result": {
"Id": "2ab8f5fa-02a7-4e91-a426-ef09adab3fc8",
"Name": "Product",
"Description": "",
"ProductStatus": "Archived",
"CreatedAt": "2022-02-11T15:22:29.58586"
}
}

Method: PATCH

Endpoint: {{env}}/api/product/{{product_id}}/archive

Response

ParameterTypeDescription
IdguidThe product Id
NamestringThe product name
DescriptionstringThe product description
ProducStatusstringThe status for the product
CreatedAtdateThe creation date for the product

Use this endpoint if you want to archive a product.

Unarchive a product#

Use this endpoint if you want to unarchive a product. Once unarchived, the product will be visible in any end user facing screens. If there are any active subscriptions or invoices they will remain until unaffected.

{
"statusCode": 200,
"message": "PATCH Request successful.",
"isError": false,
"result": {
"Id": "2ab8f5fa-02a7-4e91-a426-ef09adab3fc8",
"Name": "Product",
"Description": "",
"ProductStatus": "Active",
"CreatedAt": "2022-02-11T15:22:29.58586"
}
}

Method: PATCH

Endpoint: {{env}}/api/product/{{product_id}}/unarchive

Response

ParameterTypeDescription
IdguidThe product Id
NamestringThe product name
DescriptionstringThe product description
ProducStatusstringThe status for the product
CreatedAtdateThe creation date for the product

Delete a product#

Use this endpoint if you want to delete a product. Once delete, the product will not be visible or avaliable to any end user or administrator.

{
"statusCode": 200,
"message": "DELETE Request successful.",
"isError": false,
"result": "Request completed"
}

Method: DELETE

Endpoint: {{env}}/api/product/{{product_id}}