Subscriptions

Creating a new subscription#

Use this endpoint if you want to add a new subscription.

{
"UserId": "c11cc378-7f58-4e29-9a9e-8f34ac8173be",
"ProductPriceId": "38e3da09-d722-4a81-8aa7-1a9cf2f91372",
"Quantity": 1,
"InvoicePaymentType": "NotifyUser",
"PaymentGateways": [
"Eft",
"Interac",
"VisaDirect"
],
"Memo": "Test",
"BillingDay": null,
"AnnuallyBillingDay": null,
"AnnuallyBillingMonth": null,
"DueDay": 30,
"LastDayOfTheMonth": true
}

Method: POST

Endpoint: {{env}}/api/subscription

Input parameters

ParameterTypeMandatoryDescription
AnnuallyBillingDayintyesBilling day for anual product prices (1-28)
AnnuallyBillingMonthintyesBilling month for anual product price (0-11)
BillingDayintyesBilling day for monthy product prices (1-28)
DueDayintyesDays to due date
InvoicePaymentTypeintyesPayment Type Operator
LastDayOfTheMonthbooleannoSet to true if you to use the last day of the month to be used has a billing day (can be used with monthy and anual product prices)
MemostringnoMemo that will be reflect on invoices and transactions
QuantityintyesDesired quantity for the product
PaymentGatewaysstring[]yesPayment gateways through witch the subscription will be processed
ProductPriceIdguidyesId for the product price
UserIdguidyesId for the user that will be charged for the subscription
StartDateTypestringnoStart Date Type Operator
StartDatedateyes (if start date type custom is selected)Desired start date
EndDateTypestringnoEnd Date Type Operator
EndDatedateyes (if end date type custom is selected)Desired end date
BillingCycleintyes (if end date type billing cycles is selected)Desired number od billing cycles
info

Differently from invoices, subscriptions only accept one product, witch can only be of the recurrent type

PaymentType

TypeBehavior
AutomaticallyChargeAutomatically charge the user by initiating a transaction has soon as possible on the selected Rails
NotifyUserEmail invoice to the user to pay manually

PaymentGateway

TypeBehavior
EftProcess through Eft
InteracProcess through Interac
VisaDirectProcess through VisaDirect
CreditCardProcess through CreditCard

Start Date Type

TypeBehavior
CustomStartDateSet a custom start date
NextMonthSet to the first day of the next month
FirstInvoiceDateSet to the first invoice date based on the invoice date calculation

End Date Type

TypeBehavior
CustomEndDateSet a custom end date
BillingCyclesSet the number of billing cycles upon witch the end date will be calculated
NeverNever ends the subscription

Response

ParameterTypeDescription
IdguidId for the subscription
TotaldecimalTotal amount for the subscription
CreatedAtdateCreation date for the subscription
ProductNamestringName for the product related to subscription
SubscriptionStatusstringSubscription status
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserBasic User data
FirstNamestringUser first name
LastNamestringUser Last name
CompanyNamestringUser Company
IsActivebooleanIndicates if the user is active or not
EmailstringUser email
IdguidId for the user that is related to the subscription
ProductPriceProduct price related to product
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
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
EnableSubscriptionEndDatebooleanEnable subscription end date
SubscriptionEndDatedateSubscription end date
ProductProduct related to product price
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer

Update a subscription#

Zūm supports changing existing subscriptions without having to cancel and recreate them. Some of the most significant changes you might make are:

Changing the quantity of products within the subscription Changing the method/way of payment collection

{
"UserId": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
"ProductPriceId": "8e881238-170a-4dd1-bc00-81e315522e33",
"Quantity": 4,
"InvoicePaymentType": "AutomaticallyCharge",
"PaymentGateways": [
"Eft"
],
"Memo": "Thank you",
"BillingDay": null,
"BillingDayOfMonth": null,
"AnnuallyBillingDay": null,
"AnnuallyBillingMonth": null,
"DueDay": 30,
"LastDayOfTheMonth": true,
"TaxRates": null,
"Shipping": null,
"SecurityPassword": "your_password"
}

Method: PUT

Endpoint: {{env}}/api/subscription/{{subscription_id}}

Use this endpoint if you want to add a new subscription.

Input parameters

ParameterTypeMandatoryDescription
IdguidyesId for the subscription
AnnuallyBillingDayintyesBilling day for anual product prices (1-28)
AnnuallyBillingMonthintyesBilling month for anual product price (0-11)
BillingDayintyesBilling day for monthy product prices (1-28)
DueDayintyesDays to due date
InvoicePaymentTypeintyesPayment Type Operator
LastDayOfTheMonthbooleannoSet to true if you to use the last day of the month to be used has a billing day (can be used with monthy and anual product prices)
MemostringnoMemo that will be reflect on invoices and transactions
QuantityintyesDesired quantity for the product
PaymentGatewaysstring[]yesPayment gateways through witch the subscription will be processed
ProductPriceIdguidyesId for the product price
UserIdguidyesId for the user that will be charged for the subscription
StartDateTypestringnoStart Date Type Operator
StartDatedateyes (if start date type custom is selected)Desired start date
EndDateTypestringnoEnd Date Type Operator
EndDatedateyes (if end date type custom is selected)Desired end date
BillingCycleintyes (if end date type billing cycles is selected)Desired number od billing cycles
SecurityPasswordstringyesYour security password

Response

ParameterTypeDescription
IdguidId for the subscription
TotaldecimalTotal amount for the subscription
CreatedAtdateCreation date for the subscription
ProductNamestringName for the product related to subscription
SubscriptionStatusstringSubscription status
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserBasic User data
FirstNamestringUser first name
LastNamestringUser Last name
CompanyNamestringUser Company
IsActivebooleanIndicates if the user is active or not
EmailstringUser email
IdguidId for the user that is related to the subscription
ProductPriceProduct price related to product
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
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
EnableSubscriptionEndDatebooleanEnable subscription end date
SubscriptionEndDatedateSubscription end date
ProductProduct related to product price
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer

Get a specific subscription#

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

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"Id": "8fc541a7-f8c8-49d4-a6cf-61348f2dd9b2",
"CustomerId": "e37f2f7a-111e-4c3f-9f83-8092dd5ef937",
"UserId": "0ba8d50e-a61d-45a4-b679-04ac466595f8",
"User": {
"Id": "0ba8d50e-a61d-45a4-b679-04ac466595f8",
"CreatedAt": "2022-01-31T19:15:01.458104",
"AccountType": "Personal",
"Name": "Jonathan Doe",
"FirstName": "Jonathan",
"LastName": "Doe",
"CompanyName": "",
"ShippingSameAsBilling": false,
"LastRefresh": "0001-01-01T00:00:00",
"Customer": {
"Id": "e37f2f7a-111e-4c3f-9f83-8092dd5ef937",
"CompanyName": "All Rails Customer"
},
"Addresses": [],
"TransactionMethodsAvailable": {
"Interac": false,
"Eft": true,
"VisaDirectPull": true,
"VisaDirectPush": true,
"CreditCard": true
}
},
"ProductPriceId": "9b497b25-74b5-41c2-bbf2-93cfa40c6bbd",
"ProductPrice": {
"Id": "9b497b25-74b5-41c2-bbf2-93cfa40c6bbd",
"ProductId": "85d9ebd9-daf7-4146-ba1d-bf1f401b8933",
"CreatedAt": "2022-02-09T18:19:05.452181",
"ProductPriceType": "Standard",
"ProductPriceStatus": "Active",
"Price": 22.45,
"PerUnit": 0,
"Frequency": "Recurring",
"PlanName": "Test",
"BillingPeriod": "Weekly",
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0,
"Currency": "CAD",
"Product": {
"Id": "85d9ebd9-daf7-4146-ba1d-bf1f401b8933",
"Name": "Test",
"ProductStatus": "Archived",
"CustomerId": "e37f2f7a-111e-4c3f-9f83-8092dd5ef937"
}
},
"Memo": "Thank you",
"DueDay": 30,
"BillingDay": 2,
"LastDayOfTheMonth": false,
"Quantity": 1,
"AnnuallyBillingDay": 0,
"AnnuallyBillingMonth": 0,
"StartDate": "2022-02-10T00:00:00",
"InvoicePaymentType": "AutomaticallyCharge",
"PaymentGateways": [
"Eft"
],
"SubscriptionStatus": "Active",
"EndDateType": "Never",
"CreatedAt": "2022-02-09T18:19:13.815643",
]
}
}

Method: GET

Endpoint: {{env}}/api/subscription/{subscription_id}

Response

ParameterTypeDescription
IdguidId for the subscription
TotaldecimalTotal amount for the subscription
CreatedAtdateCreation date for the subscription
ProductNamestringName for the product related to subscription
SubscriptionStatusstringSubscription status
AnnuallyBillingDayintBilling day for anual product prices (1-28)
AnnuallyBillingMonthintBilling month for anual product price (0-11)
BillingDayintBilling day for monthy product prices (1-28)
DueDayintDays to due date
InvoicePaymentTypeintPayment Type Operator
LastDayOfTheMonthbooleanSet to true if you to use the last day of the month to be used has a billing day (can be used with monthy and anual product prices)
MemostringMemo that will be reflect on invoices and transactions
QuantityintDesired quantity for the product
PaymentGatewaysstring[]Payment gateways through witch the subscription will be processed
ProductPriceIdguidId for the product price
UserIdguidId for the user that will be charged for the subscription
StartDateTypestringStart Date Type Operator
StartDatedateDesired start date
EndDateTypestringEnd Date Type Operator
EndDatedateDesired end date
BillingCycleintDesired number od billing cycles
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserBasic User data
FirstNamestringUser first name
LastNamestringUser Last name
CompanyNamestringUser Company
IsActivebooleanIndicates if the user is active or not
EmailstringUser email
IdguidId for the user that is related to the subscription
ProductPriceProduct price related to product
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
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
EnableSubscriptionEndDatebooleanEnable subscription end date
SubscriptionEndDatedateSubscription end date
ProductProduct related to product price
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer

Search a subscription#

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

{
"CreatedAt": "2022-02-16T03:00:00.000Z",
"CreatedAtOperator": "isBefore",
"SubscriptionStatus": 0,
"UserName": "Doe",
"UserNameOperator": "contains",
"GenericSearch": "Doe",
"Pagination": {
"PageNumber": 1,
"ItemsPerPage": 10
}
}

Method: POST

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

Input parameters

ParameterTypeMandatoryDescription
GenericSearchstringnoFilter subscription by subscription id, user name and user email
SubscriptionStatusstringnoSubscription status
CreatedAtdatetimenoCreate date
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
UserNamestringnoUsername value
UserNameOperatorstringnoUsername Operator
Paginationno
PageNumbernumbernoThe respective page, starting at 1
ItemsPerPagenumbernoThe quantity of items per page

Response

ParameterTypeDescription
CurrentPagenumberThe current page
PageSizenumberThe amount of rows returned in the current page
TotalCountnumberThe total rows the filter returns
ItemsList of subscriptions
IdguidId for the subscription
TotaldecimalTotal amount for the subscription
CreatedAtdateCreation date for the subscription
ProductNamestringName for the product related to subscription
SubscriptionStatusstringSubscription status
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserBasic User data
FirstNamestringUser first name
LastNamestringUser Last name
CompanyNamestringUser Company
IsActivebooleanIndicates if the user is active or not
EmailstringUser email
IdguidId for the user that is related to the subscription
ProductPriceProduct price related to product
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
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
EnableSubscriptionEndDatebooleanEnable subscription end date
SubscriptionEndDatedateSubscription end date
ProductProduct related to product price
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer

Cancel a subscription#

Use this endpoint if you want to cancel a subscription.

{
"CancellationType": "CustomDate",
"CustomCancellationDate": "2022-02-18T03:00:00.000Z",
"CancellationReason": "Other",
"CustomCancellationReason": "I want to test the cancel subscription feature",
"RefundLastInvoice": true,
"SecurityPassword": "your_password"
}

Method: PUT

Endpoint: {{env}}/api/subscription/cancel/{{subscription_id}}

Input parameters

ParameterTypeMandatoryDescription
CancellationReasonstringnoCancellationReason
CancellationTypestringnoCancellation Type
CustomCancellationDatedatetimeyes (only if CancellationReason is CustomDate)Desired cancellation date
CustomCancellationReasonstringyes (only if CancellationReason is Other)Description for the cancellation reason
RefundLastInvoiceboolnoRefund the last processed Invoice
SecurityPasswordstringyesYour password

Cancellation Reasons

TypeDescription
TooExpensiveThis is too expensive
AccidentThis was created by accident
DifferentProductI want a different product/variety
NoNeedI no longer need this product
SoonerI need it sooner
OtherOther

Cancellation Type

TypeBehavior
ImmediatelyCancel the subscription rigtht away
EndOfCurrentPeriodWait for the next billing period and then cancels the subscription
CustomDateSet the cancellation to a chosen date

Get subscription events#

Use this endpoint if you want to get all the subscription events related to a specific subscription.

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": [
{
"CreatedAt": "2021-11-03T15:37:47.328195",
"Description": "Subscription status has changed to Cancelled",
"Type": "StatusChanged",
"SubscriptionId": "bab3a770-484d-48d6-b89e-77485a05fe97"
},
{
"CreatedAt": "2021-10-27T19:45:58.323213",
"Description": "Subscription bab3a770-484d-48d6-b89e-77485a05fe97 was created",
"Type": "Created",
"SubscriptionId": "bab3a770-484d-48d6-b89e-77485a05fe97"
}
]
}

Method: GET

Endpoint: {{env}}/api/subscription/getsubscriptionevents/{{subscription_id}}

Response

A list of:

ParameterTypeDescription
InvoiceIdguidId for the subscription
CreatedAtdateCreation date for the subscription event
DescriptionstringUser friendly description for the event
TypestringEvent Type

Subscription Event Type

TypeBehavior
CreatedSubscription was created
UpdatedSubscription was edited
StatusChangedSubscription status was changed

Get subscription invoices#

Use this endpoint if you want to get all the invoices related to a specific subscription.

{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": [
{
"Id": "e0a79d0e-611a-40d7-973a-e41a09fc3021",
"UserId": "41ee276c-bd09-46ee-a9e0-28f5d23e07d5",
"User": {
"Id": "41ee276c-bd09-46ee-a9e0-28f5d23e07d5",
"FirstName": "renan",
"LastName": "zacheo",
"Email": "renan@gmail.com",
"IsActive": true
},
"CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
"Customer": {
"Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
"CompanyName": "Sam's Gym"
},
"CreatedAt": "2021-11-27T05:05:12.776243",
"Amount": 100,
"InvoiceStatus": "Paid",
"Memo": "Thank you for your business!",
"DaysToDueDate": 0,
"DueDate": "2021-11-27T00:00:00",
"PaymentType": "AutomaticallyCharge",
"PaymentGateways": [
"Eft"
],
"Items": [
{
"ProductPrice": {
"Id": "e1ddcecd-dc9c-41ee-b762-49056532b727",
"ProductId": "ba01bbed-a741-419a-839b-17c5baa30f39",
"CreatedAt": "2021-10-27T16:12:14.536959",
"ProductPriceType": "Standard",
"ProductPriceStatus": "Active",
"Price": 100,
"PerUnit": 0,
"Frequency": "Recurring",
"PlanName": "Silver member",
"BillingPeriod": "Monthly",
"EnableSubscriptionEndDate": false,
"EnableFreeTrial": false,
"FreeTrialInDays": 0,
"EnableSetupFee": false,
"SetupFee": 0,
"Currency": "CAD",
"Product": {
"Id": "ba01bbed-a741-419a-839b-17c5baa30f39",
"Name": "Gym ",
"Description": "gym membership",
"ProductStatus": "Archived",
"CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035"
}
},
"ProductPriceId": "e1ddcecd-dc9c-41ee-b762-49056532b727",
"Quantity": 1,
"Currency": "CAD",
"Price": 100
}
],
"Transactions": [
{
"FastEft": false,
"Id": "63a77973-702a-4ab9-9dad-985a2439fdf5",
"CreatedAt": "2021-11-27T05:05:13.391365",
"Memo": "Thank you for your business!",
"Comment": "",
"Amount": 100,
"Customer": {
"Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
"CompanyName": "Sam's Gym"
},
"User": {
"Id": "41ee276c-bd09-46ee-a9e0-28f5d23e07d5",
"FirstName": "renan",
"LastName": "zacheo",
"Email": "renan@gmail.com",
"IsActive": true
},
"ZumRailsType": "AccountsReceivable",
"TransactionMethod": "Eft",
"TransactionHistory": [],
"TransactionStatus": "Completed",
"From": "renan zacheo - renan@gmail.com",
"To": "Not able to parse",
"InteracHasSecurityQuestionAndAnswer": false,
"CompletedAt": "2021-11-27T05:06:13.019093",
"IsRefundable": false,
"InvoiceId": "e0a79d0e-611a-40d7-973a-e41a09fc3021",
"SubscriptionId": "b270fca6-f811-4d06-a4c9-32aa88565a48"
}
],
}
]
}

Method: GET

Endpoint: {{env}}/api/subscription/getsubscriptioninvoices/{{subscription_id}}

Response

A list of:

ParameterTypeDescription
IdguidId for the invoice
AmountdecimalTotal amount for the invoice
CreatedAtdateCreation date for the invoice
CustomerIdguidId for the related customer
DaysToDueDateintDays until due date from the creation date
DueDatedateDue date
InvoiceStatusstringInvoice status
MemostringMemo that will be reflected on the transactions
PaymentTypestringPaymentType Operator
PaymentGatewaysstring[]PaymentGateways Operator
UserIdguidId for the user that is related to the invoice
CustomerBasic Customer data
CompanyNamestringCompany Name
IdguidId for the related customer
UserBasic User data
FirstNamestringUser first name
LastNamestringUser Last name
CompanyNamestringUser Company
IsActivebooleanIndicates if the user is active or not
EmailstringUser email
IdguidId for the user that is related to the invoice
Items
OneOffProductNamestringName for the one-off product
OneOffProductAmountdecimalAmount for each unit or package
QuantityintQuantity for the product price
CurrencystringCurrency set for the product price
PricedecimalPrice amount for each unit or package
ProductPriceIdguidId for the related product price
ProductPriceProduct price related to product
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
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
ProductProduct related to product price
IdguidId for the Product
NamestringProduct name
DescriptionstringProduct Description
ProductStatusstringProduct status
CustomerIdguidId for the related customer
TransactionsTransactions related to the invoice
IdguidId for the transaction
AmountdecimalTotal amount for the transaction
CommentstringComment fo the transaction
CreatedAtdateCreation date for the transaction
FastEftbooleanIndicates if this was a fast eft or not
FromstringFrom description for the transaction
InvoiceIdguidId for the related Invoice
IsRefundablebooleanIndicates if the transaction is IsRefundable
MemostringMemo for the transaction
TostringTo description for the transaction
TransactionMethodstringTransaction method for the transaction
TransactionStatusstringStatus for the transaction
ZumRailsTypestringZumRailsType Operator for the transaction