Subscriptions

Creating a new subscription

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

Method: POST

Endpoint: {{env}}/api/subscription

Payload

{
  "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,
  "TaxRates": [],
  "CommonFees": []
}

Payload for scheduled 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,
  "BillingDayOfMonth": 28,
  "AnnuallyBillingDay": null,
  "AnnuallyBillingMonth": null,
  "DueDay": 30,
  "LastDayOfTheMonth": false,
  "BillingCycle": 23,
  "EndDate": null,
  "StartDate": null,
  "StartDateType": "NextMonth",
  "EndDateType": "BillingCycles",
  "TaxRates": [],
  "CommonFees": []
}

Response

{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {
    "Id": "467e7df2-bbc1-4028-88f9-cebc1db52c3c",
    "Customer": {
      "Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
      "CompanyName": "Sam's Gym"
    },
    "User": {
      "Id": "c11cc378-7f58-4e29-9a9e-8f34ac8173be",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "[e-mail]",
      "IsActive": true
    },
    "ProductName": "gym",
    "CreatedAt": "2022-02-15T15:04:00.5499962Z",
    "SubscriptionStatus": "Scheduled",
    "ProductPrice": {
      "Id": "38e3da09-d722-4a81-8aa7-1a9cf2f91372",
      "ProductId": "b4518805-b310-448b-8d6c-20a55e22a61d",
      "CreatedAt": "2021-10-27T19:18:12.956011",
      "ProductPriceType": "Standard",
      "ProductPriceStatus": "Active",
      "Price": 100,
      "PerUnit": 0,
      "Frequency": "Recurring",
      "PlanName": "gold member",
      "BillingPeriod": "Monthly",
      "EnableSubscriptionEndDate": true,
      "SubscriptionEndDate": "2022-10-30T00:00:00",
      "EnableFreeTrial": false,
      "FreeTrialInDays": 0,
      "EnableSetupFee": true,
      "SetupFee": 10,
      "Currency": "CAD",
      "Product": {
        "Id": "b4518805-b310-448b-8d6c-20a55e22a61d",
        "Name": "gym",
        "ProductStatus": "Active",
        "CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035"
      }
    },
    "Total": 100,
    "TaxRates": [],
    "CommonFees": []
  }
}

Input parameters

Parameter	Type	Mandatory	Description
AnnuallyBillingDay	int	yes	Billing day for annual product prices (1-28)
AnnuallyBillingMonth	int	yes	Billing month for annual product price (0-11)
BillingDay	int	yes	Billing day for monthly product prices (1-28)
DueDay	int	yes	Days to due date
InvoicePaymentType	int	yes	Payment Type Operator
LastDayOfTheMonth	boolean	no	Set to true if you to use the last day of the month to be used has a billing day (can be used with monthly and annual product prices)
Memo	string	no	Memo that will be reflect on invoices and transactions
Quantity	int	yes	Desired quantity for the product
PaymentGateways	string[]	yes	Payment gateways through witch the subscription will be processed
ProductPriceId	guid	yes	Id for the product price
UserId	guid	yes	Id for the user that will be charged for the subscription
StartDateType	string	no	Start Date Type Operator
StartDate	date	yes (if start date type custom is selected)	Desired start date
EndDateType	string	no	End Date Type Operator
EndDate	date	yes (if end date type custom is selected)	Desired end date
BillingCycle	int	yes (if end date type billing cycles is selected)	Desired number od billing cycles
TaxRates		no	Tax rates that will be included on the subscription
Id	guid	no	Id for the tax rate
Name	string	no	Name for the tax rate
Description	string	no	Description for the tax rate
Type	string	no	The type is "Exclusive" or "Inclusive"
Value	int	no	The tax value in percentage
ClassName	string	no	The class name value is "TaxRate"
CommonFees		no	Fees that will be included on the subscription
Id	guid	no	Id for the common fee
Name	string	no	Name for the common fee
Description	string	no	Description for the common fee
Value	int	no	The value for the common fee
ClassName	string	no	The class name value is "CommonFee"

INFO

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

PaymentType

Type	Behavior
AutomaticallyCharge	Automatically charge the user by initiating a transaction has soon as possible on the selected Rails
NotifyUser	Email invoice to the user to pay manually

PaymentGateway

Type	Behavior
Eft	Process through Eft
Interac	Process through Interac
VisaDirect	Process through VisaDirect
CreditCard	Process through CreditCard

Start Date Type

Type	Behavior
CustomStartDate	Set a custom start date
NextMonth	Set to the first day of the next month
FirstInvoiceDate	Set to the first invoice date based on the invoice date calculation

End Date Type

Type	Behavior
CustomEndDate	Set a custom end date
BillingCycles	Set the number of billing cycles upon witch the end date will be calculated
Never	Never ends the subscription

Response

Parameter	Type	Description
Id	guid	Id for the subscription
Total	decimal	Total amount for the subscription
CreatedAt	date	Creation date for the subscription
ProductName	string	Name for the product related to subscription
SubscriptionStatus	string	Subscription status
Customer		Basic Customer data
CompanyName	string	Company Name
Id	guid	Id for the related customer
User		Basic User data
FirstName	string	User first name
LastName	string	User Last name
CompanyName	string	User Company
IsActive	boolean	Indicates if the user is active or not
Email	string	User email
Id	guid	Id for the user that is related to the subscription
ProductPrice		Product price related to product
Id	string	The Id for the product price
ProductId	string	The Id for the product on witch is related
CreatedAt	date	Creation date
ProductPriceType	string	Price Model
ProductPriceStatus	string	Status for the product price
Price	decimal	Price
PerUnit	string	Package size
Frequency	string	Price frequency
EnableFreeTrial	bool	Enable free trial feature
FreeTrialInDays	int	Number of days for free trial
EnableSetupFee	bool	Enable setup fee
SetupFee	decimal	Number of days for free trial
Currency	string	Currency set for the product price
EnableSubscriptionEndDate	boolean	Enable subscription end date
SubscriptionEndDate	date	Subscription end date
Product		Product related to product price
Id	guid	Id for the Product
Name	string	Product name
Description	string	Product Description
ProductStatus	string	Product status
CustomerId	guid	Id for the related customer
TaxRates		Tax rates that will be included on the subscription
Id	guid	Id for the tax rate
Name	string	Name for the tax rate
Description	string	Description for the tax rate
Type	string	The type is "Exclusive" or "Inclusive"
Value	int	The tax value in percentage
ClassName	string	The class name value is "TaxRate"
CommonFees		Fees that will be included on the subscription
Id	guid	Id for the common fee
Name	string	Name for the common fee
Description	string	Description for the common fee
Value	int	The value for the common fee
ClassName	string	The class name value is "CommonFee"

Update a subscription

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

Method: PUT

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

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

Payload

{
  "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,
  "CommonFees": null
}

Response

{
  "statusCode": 200,
  "message": "PUT Request successful.",
  "isError": false,
  "result": {
    "Id": "4472acd4-e2f6-4dc9-9638-a567b288b619",
    "CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
    "Customer": {
      "CompleteEftTransactionInDays": 1,
      "RbcInteracEnabled": false,
      "EftProvider": "RBC",
      "CreditCardProvider": "AuthorizeNet",
      "EntityStatus": "Active",
      "BankAccountInformationOrigin": "ZumRails",
      "CustomerType": "Customer",
      "WebhookSecret": "4134dfea0e3b4964a95d6350a120328c",
      "EftCustomLimitsEnabled": true,
      "EftTransactionQuantityLimitPerDay": 100,
      "EftTransactionAmountLimitPerDay": 100.99,
      "InteracCustomLimitsEnabled": true,
      "InteracTransactionQuantityLimitPerDay": 200,
      "InteracTransactionAmountLimitPerDay": 200.99,
      "VisaCardCustomLimitsEnabled": true,
      "VisaCardTransactionQuantityLimitPerDay": 200,
      "VisaCardTransactionAmountLimitPerDay": 300.99,
      "CreditCardCustomLimitsEnabled": true,
      "CreditCardTransactionQuantityLimitPerDay": 200,
      "CreditCardTransactionAmountLimitPerDay": 400.99,
      "AutomaticDailyWithdraw": false,
      "GroupByBatchFile": false,
      "HasDirectSettlementAccount": false,
      "LoginType": "EmailPassword",
      "Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
      "CompanyName": "Sam's Gym",
      "TransactionDescriptionType": "Fixed",
      "TransactionDescription": "AAA",
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "[e-mail]",
      "PhoneNumber": "1111111122222",
      "AddressStreet": "rua",
      "AddressCity": "montreal",
      "AddressProvince": "QC",
      "AddressPostalCode": "a1a1a1",
      "MonthlyCost": 0,
      "CostPerTransaction": 0,
      "CostPerUser": 0,
      "CostPerBankRefresh": 0,
      "CostPerNSF": 0,
      "PercentagePerTransaction": 0,
      "PercentagePerUser": 0,
      "PercentagePerBankRefresh": 0,
      "PercentagePerNSF": 0,
      "CustomerAccountStatus": "Active",
      "CustomerBillingType": "PercentageSplit",
      "PartnerId": "4d3a4670-f26d-40d6-8dbe-3769397bf5de",
      "WebhookUrl": "https://zumrails.requestcatcher.com/test",
      "WebhookConfigurations": [
        {
          "WebhookType": "Transaction",
          "Name": "EftFailedInsufficientFunds",
          "StatusValue": 901
        },
        {
          "WebhookType": "Transaction",
          "Name": "EftFailedInsufficientFunds",
          "StatusValue": 901
        },
        {
          "WebhookType": "Transaction",
          "Name": "InteracAcknowledgedDebit",
          "StatusValue": 202
        }
      ],
      "NotificationConfigurations": [
        {
          "Id": "540f30de-fcca-434d-a6f8-27b08b3a3044",
          "Method": "Email",
          "Type": "TransactionFailure",
          "TransactionMethod": "Interac",
          "TransactionEvents": [
            "InteracFailedGenericError",
            "InteracFailedInvalidEmailFormat"
          ],
          "Emails": ["[e-mail]"]
        },
        {
          "Id": "af48810c-27e9-4119-8cbf-3e7dd6dc33ac",
          "Method": "Email",
          "Type": "TransactionFailure",
          "TransactionMethod": "Interac",
          "TransactionEvents": ["InteracFailedGenericError"],
          "Emails": ["[e-mail]"]
        }
      ],
      "CustomerBillingPrices": [],
      "ActivationDate": "2021-06-30T18:24:06.458786",
      "CreatedAt": "2021-06-30T18:24:06.458875",
      "TransacionMethodVisaDirectEnabled": true,
      "TransacionMethodEftEnabled": true,
      "TransacionMethodInteracEnabled": true,
      "TransacionMethodCreditCardEnabled": true,
      "HasUnifiedWallet": true,
      "LogoURL": "",
      "PrimaryColor": "#FF0000",
      "ConnectRedirectSuccessURL": "",
      "VerifyCreditCard": false,
      "PeoplesTrustInteracEnabled": false,
      "PeoplesTrustInteracNotificationsEnabled": false,
      "CustomerCsvDelimiter": "Comma",
      "IsTwoFactorAuthenticationEnabled": false
    },
    "UserId": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
    "User": {
      "Id": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
      "CreatedAt": "2021-06-30T18:28:59.650781",
      "AccountType": "Personal",
      "Name": "John Doe",
      "FirstName": " John",
      "LastName": "Doe",
      "PhoneNumber": "514-123-1234",
      "ShippingSameAsBilling": false,
      "Email": "[e-mail]",
      "LastRefresh": "0001-01-01T00:00:00",
      "Customer": {
        "Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
        "CompanyName": "Sam's Gym"
      },
      "Addresses": [],
      "TransactionMethodsAvailable": {
        "Interac": true,
        "Eft": true,
        "VisaDirectPull": false,
        "VisaDirectPush": false,
        "CreditCard": false
      }
    },
    "ProductPriceId": "8e881238-170a-4dd1-bc00-81e315522e33",
    "ProductPrice": {
      "Id": "8e881238-170a-4dd1-bc00-81e315522e33",
      "ProductId": "4986c149-f8f3-4789-82e9-f07b32c9c000",
      "CreatedAt": "2021-10-27T19:29:51.836045",
      "ProductPriceType": "Package",
      "ProductPriceStatus": "Active",
      "Price": 10,
      "PerUnit": 1,
      "Frequency": "Recurring",
      "PlanName": "Gym",
      "BillingPeriod": "Monthly",
      "EnableSubscriptionEndDate": false,
      "EnableFreeTrial": false,
      "FreeTrialInDays": 0,
      "EnableSetupFee": false,
      "SetupFee": 0,
      "Currency": "CAD",
      "Product": {
        "Id": "4986c149-f8f3-4789-82e9-f07b32c9c000",
        "Name": "test sub",
        "ProductStatus": "Active",
        "CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035"
      }
    },
    "Memo": "Thank you",
    "DueDay": 30,
    "LastDayOfTheMonth": true,
    "Quantity": 4,
    "AnnuallyBillingDay": 0,
    "AnnuallyBillingMonth": 0,
    "StartDate": "2022-02-16T00:00:00",
    "InvoicePaymentType": "AutomaticallyCharge",
    "PaymentGateways": ["Eft"],
    "SubscriptionStatus": "Active",
    "EndDateType": "Never",
    "CreatedAt": "2022-02-15T18:25:07.749224",
    "TaxRates": [],
    "CommonFees": []
  }
}

Input parameters

Parameter	Type	Mandatory	Description
Id	guid	yes	Id for the subscription
AnnuallyBillingDay	int	yes	Billing day for annual product prices (1-28)
AnnuallyBillingMonth	int	yes	Billing month for annual product price (0-11)
BillingDay	int	yes	Billing day for monthly product prices (1-28)
DueDay	int	yes	Days to due date
InvoicePaymentType	int	yes	Payment Type Operator
LastDayOfTheMonth	boolean	no	Set to true if you to use the last day of the month to be used has a billing day (can be used with monthly and annual product prices)
Memo	string	no	Memo that will be reflect on invoices and transactions
Quantity	int	yes	Desired quantity for the product
PaymentGateways	string[]	yes	Payment gateways through witch the subscription will be processed
ProductPriceId	guid	yes	Id for the product price
UserId	guid	yes	Id for the user that will be charged for the subscription
StartDateType	string	no	Start Date Type Operator
StartDate	date	yes (if start date type custom is selected)	Desired start date
EndDateType	string	no	End Date Type Operator
EndDate	date	yes (if end date type custom is selected)	Desired end date
BillingCycle	int	yes (if end date type billing cycles is selected)	Desired number od billing cycles
TaxRates		no	Tax rates that will be included on the subscription
Id	guid	no	Id for the tax rate
Name	string	no	Name for the tax rate
Description	string	no	Description for the tax rate
Type	string	no	The type is "Exclusive" or "Inclusive"
Value	int	no	The tax value in percentage
ClassName	string	no	The class name value is "TaxRate"
CommonFees		no	Fees that will be included on the subscription
Id	guid	no	Id for the common fee
Name	string	no	Name for the common fee
Description	string	no	Description for the common fee
Value	int	no	The value for the common fee
ClassName	string	no	The class name value is "CommonFee"

Response

Parameter	Type	Description
Id	guid	Id for the subscription
Total	decimal	Total amount for the subscription
CreatedAt	date	Creation date for the subscription
ProductName	string	Name for the product related to subscription
SubscriptionStatus	string	Subscription status
Customer		Basic Customer data
CompanyName	string	Company Name
Id	guid	Id for the related customer
User		Basic User data
FirstName	string	User first name
LastName	string	User Last name
CompanyName	string	User Company
IsActive	boolean	Indicates if the user is active or not
Email	string	User email
Id	guid	Id for the user that is related to the subscription
ProductPrice		Product price related to product
Id	string	The Id for the product price
ProductId	string	The Id for the product on witch is related
CreatedAt	date	Creation date
ProductPriceType	string	Price Model
ProductPriceStatus	string	Status for the product price
Price	decimal	Price
PerUnit	string	Package size
Frequency	string	Price frequency
EnableFreeTrial	bool	Enable free trial feature
FreeTrialInDays	int	Number of days for free trial
EnableSetupFee	bool	Enable setup fee
SetupFee	decimal	Number of days for free trial
Currency	string	Currency set for the product price
EnableSubscriptionEndDate	boolean	Enable subscription end date
SubscriptionEndDate	date	Subscription end date
Product		Product related to product price
Id	guid	Id for the Product
Name	string	Product name
Description	string	Product Description
ProductStatus	string	Product status
CustomerId	guid	Id for the related customer
TaxRates		Tax rates that will be included on the subscription
Id	guid	Id for the tax rate
Name	string	Name for the tax rate
Description	string	Description for the tax rate
Type	string	The type is "Exclusive" or "Inclusive"
Value	int	The tax value in percentage
ClassName	string	The class name value is "TaxRate"
CommonFees		Fees that will be included on the subscription
Id	guid	Id for the common fee
Name	string	Name for the common fee
Description	string	Description for the common fee
Value	int	The value for the common fee
ClassName	string	The class name value is "CommonFee"

Get a specific subscription

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

Method: GET

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

Response

{
  "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",
    ]
  }
}

Response

Parameter	Type	Description
Id	guid	Id for the subscription
Total	decimal	Total amount for the subscription
CreatedAt	date	Creation date for the subscription
ProductName	string	Name for the product related to subscription
SubscriptionStatus	string	Subscription status
AnnuallyBillingDay	int	Billing day for annual product prices (1-28)
AnnuallyBillingMonth	int	Billing month for annual product price (0-11)
BillingDay	int	Billing day for monthly product prices (1-28)
DueDay	int	Days to due date
InvoicePaymentType	int	Payment Type Operator
LastDayOfTheMonth	boolean	Set to true if you to use the last day of the month to be used has a billing day (can be used with monthly and annual product prices)
Memo	string	Memo that will be reflect on invoices and transactions
Quantity	int	Desired quantity for the product
PaymentGateways	string[]	Payment gateways through witch the subscription will be processed
ProductPriceId	guid	Id for the product price
UserId	guid	Id for the user that will be charged for the subscription
StartDateType	string	Start Date Type Operator
StartDate	date	Desired start date
EndDateType	string	End Date Type Operator
EndDate	date	Desired end date
BillingCycle	int	Desired number od billing cycles
Customer		Basic Customer data
CompanyName	string	Company Name
Id	guid	Id for the related customer
User		Basic User data
FirstName	string	User first name
LastName	string	User Last name
CompanyName	string	User Company
IsActive	boolean	Indicates if the user is active or not
Email	string	User email
Id	guid	Id for the user that is related to the subscription
ProductPrice		Product price related to product
Id	string	The Id for the product price
ProductId	string	The Id for the product on witch is related
CreatedAt	date	Creation date
ProductPriceType	string	Price Model
ProductPriceStatus	string	Status for the product price
Price	decimal	Price
PerUnit	string	Package size
Frequency	string	Price frequency
EnableFreeTrial	bool	Enable free trial feature
FreeTrialInDays	int	Number of days for free trial
EnableSetupFee	bool	Enable setup fee
SetupFee	decimal	Number of days for free trial
Currency	string	Currency set for the product price
EnableSubscriptionEndDate	boolean	Enable subscription end date
SubscriptionEndDate	date	Subscription end date
Product		Product related to product price
Id	guid	Id for the Product
Name	string	Product name
Description	string	Product Description
ProductStatus	string	Product status
CustomerId	guid	Id 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.

Method: POST

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

Payload

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

Response

{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {
    "CurrentPage": 1,
    "PageSize": 10,
    "TotalCount": 1,
    "Items": [
      {
        "Id": "8fc541a7-f8c8-49d4-a6cf-61348f2dd9b2",
        "Customer": {
          "Id": "e37f2f7a-111e-4c3f-9f83-8092dd5ef937",
          "CompanyName": "All Rails Customer"
        },
        "User": {
          "Id": "0ba8d50e-a61d-45a4-b679-04ac466595f8",
          "FirstName": "Jonathan",
          "LastName": "Doe",
          "CompanyName": "",
          "IsActive": true
        },
        "ProductName": "Test",
        "CreatedAt": "2022-02-09T18:19:13.815643",
        "SubscriptionStatus": "Active",
        "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"
          }
        },
        "Total": 22.9
      }
    ]
  }
}

Input parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter subscription by subscription id, user name and user email
SubscriptionStatus	string	no	Subscription status
CreatedAt	datetime	no	Create date
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties
UserName	string	no	Username value
UserNameOperator	string	no	Username Operator
Pagination		no
PageNumber	number	no	The respective page, starting at 1
ItemsPerPage	number	no	The quantity of items per page

Response

Parameter	Type	Description
CurrentPage	number	The current page
PageSize	number	The amount of rows returned in the current page
TotalCount	number	The total rows the filter returns
Items		List of subscriptions
Id	guid	Id for the subscription
Total	decimal	Total amount for the subscription
CreatedAt	date	Creation date for the subscription
ProductName	string	Name for the product related to subscription
SubscriptionStatus	string	Subscription status
Customer		Basic Customer data
CompanyName	string	Company Name
Id	guid	Id for the related customer
User		Basic User data
FirstName	string	User first name
LastName	string	User Last name
CompanyName	string	User Company
IsActive	boolean	Indicates if the user is active or not
Email	string	User email
Id	guid	Id for the user that is related to the subscription
ProductPrice		Product price related to product
Id	string	The Id for the product price
ProductId	string	The Id for the product on witch is related
CreatedAt	date	Creation date
ProductPriceType	string	Price Model
ProductPriceStatus	string	Status for the product price
Price	decimal	Price
PerUnit	string	Package size
Frequency	string	Price frequency
EnableFreeTrial	bool	Enable free trial feature
FreeTrialInDays	int	Number of days for free trial
EnableSetupFee	bool	Enable setup fee
SetupFee	decimal	Number of days for free trial
Currency	string	Currency set for the product price
EnableSubscriptionEndDate	boolean	Enable subscription end date
SubscriptionEndDate	date	Subscription end date
Product		Product related to product price
Id	guid	Id for the Product
Name	string	Product name
Description	string	Product Description
ProductStatus	string	Product status
CustomerId	guid	Id for the related customer

Cancel a subscription

Use this endpoint if you want to cancel a subscription.

Method: PUT

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

Payload

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

Response

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

Input parameters

Parameter	Type	Mandatory	Description
CancellationReason	string	no	CancellationReason
CancellationType	string	no	Cancellation Type
CustomCancellationDate	datetime	yes (only if CancellationReason is CustomDate)	Desired cancellation date
CustomCancellationReason	string	yes (only if CancellationReason is Other)	Description for the cancellation reason
RefundLastInvoice	bool	no	Refund the last processed Invoice

Cancellation Reasons

Type	Description
TooExpensive	This is too expensive
Accident	This was created by accident
DifferentProduct	I want a different product/variety
NoNeed	I no longer need this product
Sooner	I need it sooner
Other	Other

Cancellation Type

Type	Behavior
Immediately	Cancel the subscription right away
EndOfCurrentPeriod	Wait for the next billing period and then cancels the subscription
CustomDate	Set the cancellation to a chosen date

Pause a subscription

Use this endpoint if you want to pause a subscription.

Method: PUT

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

CAUTION

Subscriptions that are paused will not generate any invoices until resumed.

Payload (Indefinite Pause)

{
  "PauseDuration": "Indefinite"
}

Payload (Custom Date Pause)

{
  "PauseDuration": "CustomDate",
  "ResumeDate": "2022-02-18T03:00:00.000Z"
}

Response

{
  "statusCode": 200,
  "message": "PUT Request successful.",
  "isError": false,
  "result": "Subscription paused successfully"
}

Input parameters

Parameter	Type	Mandatory	Description
PauseDuration	PauseDuration	yes	Pause Duration
ResumeDate	datetime	no	Set a resume date for the subscriptions. This should be used only if setting a CustomDate pause duration

Pause Duration

Type	Description
Indefinite	With this configuration the subscription will never be automatically resumed
CustomDate	With this configuration you can set a given resume date for the subscription

Resume a subscription

Use this endpoint if you want to resume a subscription.

Method: PUT

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

Response

{
  "statusCode": 200,
  "message": "PUT Request successful.",
  "isError": false,
  "result": "Subscription resumed successfully"
}

Get subscription events

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

Method: GET

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

Response

{
  "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"
    }
  ]
}

Response

A list of:

Parameter	Type	Description
InvoiceId	guid	Id for the subscription
CreatedAt	date	Creation date for the subscription event
Description	string	User friendly description for the event
Type	string	Event Type

Subscription Event Type

Type	Behavior
Created	Subscription was created
Updated	Subscription was edited
StatusChanged	Subscription status was changed

Get subscription invoices

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

Method: GET

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

Response

{
  "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": "John",
        "LastName": "Doe",
        "Email": "[e-mail]",
        "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": [
        {
          "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": "John",
            "LastName": "Doe",
            "Email": "[e-mail]",
            "IsActive": true
          },
          "ZumRailsType": "AccountsReceivable",
          "TransactionMethod": "Eft",
          "TransactionHistory": [],
          "TransactionStatus": "Completed",
          "From": "John Doe - [e-mail]",
          "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"
        }
      ]
    }
  ]
}

Response

A list of:

Parameter	Type	Description
Id	guid	Id for the invoice
Amount	decimal	Total amount for the invoice
CreatedAt	date	Creation date for the invoice
CustomerId	guid	Id for the related customer
DaysToDueDate	int	Days until due date from the creation date
DueDate	date	Due date
InvoiceStatus	string	Invoice status
Memo	string	Memo that will be reflected on the transactions
PaymentType	string	PaymentType Operator
PaymentGateways	string[]	PaymentGateways Operator
UserId	guid	Id for the user that is related to the invoice
Customer		Basic Customer data
CompanyName	string	Company Name
Id	guid	Id for the related customer
User		Basic User data
FirstName	string	User first name
LastName	string	User Last name
CompanyName	string	User Company
IsActive	boolean	Indicates if the user is active or not
Email	string	User email
Id	guid	Id for the user that is related to the invoice
Items
OneOffProductName	string	Name for the one-off product
OneOffProductAmount	decimal	Amount for each unit or package
Quantity	int	Quantity for the product price
Currency	string	Currency set for the product price
Price	decimal	Price amount for each unit or package
ProductPriceId	guid	Id for the related product price
ProductPrice		Product price related to product
Id	string	The Id for the product price
ProductId	string	The Id for the product on witch is related
CreatedAt	date	Creation date
ProductPriceType	string	Price Model
ProductPriceStatus	string	Status for the product price
Price	decimal	Price
PerUnit	string	Package size
Frequency	string	Price frequency
EnableFreeTrial	bool	Enable free trial feature
FreeTrialInDays	int	Number of days for free trial
EnableSetupFee	bool	Enable setup fee
SetupFee	decimal	Number of days for free trial
Currency	string	Currency set for the product price
Product		Product related to product price
Id	guid	Id for the Product
Name	string	Product name
Description	string	Product Description
ProductStatus	string	Product status
CustomerId	guid	Id for the related customer
Transactions		Transactions related to the invoice
Id	guid	Id for the transaction
Amount	decimal	Total amount for the transaction
Comment	string	Comment fo the transaction
CreatedAt	date	Creation date for the transaction
From	string	From description for the transaction
InvoiceId	guid	Id for the related Invoice
IsRefundable	boolean	Indicates if the transaction is IsRefundable
Memo	string	Memo for the transaction
To	string	To description for the transaction
TransactionMethod	string	Transaction method for the transaction
TransactionStatus	string	Status for the transaction
ZumRailsType	string	ZumRailsType Operator for the transaction