Invoices

Creating a new invoice#

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

Method: POST

Endpoint: {{env}}/api/invoice

Payload
Response

{
  "DaysToDueDate": 30,
  "Items": [
    {
      "ProductPriceId": "8a306490-21c2-44d9-bb61-4ee6bf4f4e8c",
      "Quantity": 1,
      "OneOffProductAmount": null,
      "OneOffProductName": null
    },
    {
      "ProductPriceId": null,
      "Quantity": 1,
      "OneOffProductAmount": 6.75,
      "OneOffProductName": "Test"
    }
  ],
  "Memo": "",
  "PaymentType": "NotifyUser",
  "PaymentGateways": ["Eft", "VisaDirect", "CreditCard"],
  "UserId": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
  "TaxRates": [],
  "CommonFees": []
}

Input parameters

Parameter	Type	Mandatory	Description
DaysToDueDate	int	yes	Days until due date
GenerateAsDraft	boolean	no	Set to true if you want this invoice to be generated has a draft
Memo	string	no	Memo that will be reflected on the transactions
PaymentType	string	yes	Payment type operator
UserId	guid	yes	Id for the user that will be charged for the invoice
PaymentGateways	string[]	yes	Payment gateways through witch the invoice will be processed
Items			ProductPrices that will be included on the invoice
OneOffProductAmount	decimal	yes (if product price is One-Off)	Amount for each unit or package
OneOffProductName	string	yes (if product price is One-Off)	Name for the one-off product
ProductPriceId	guid	yes (if is a normal product)	Id for the product price
Quantity	int	yes	Desired quantity for the product
TaxRates		no	Tax rates that will be included on the invoice
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 invoice
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"

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

info

If you are creating a invoice with the AutomaticallyCharge Payment Type you should inform only one Payment Gateway

Response

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
TaxRates		Tax rates that will be included on the invoice
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 invoice
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"

info

More info about transactions can be found here

Update a invoice#

Use this endpoint if you want to update a invoice.

Method: PUT

Endpoint: {{env}}/api/invoice/{{invoice_id}}

caution

You can only update invoices that have Draft status

Payload
Response

{
  "DaysToDueDate": 30,
  "Items": [
    {
      "ProductPriceId": "8a306490-21c2-44d9-bb61-4ee6bf4f4e8c",
      "Quantity": 1,
      "OneOffProductAmount": null,
      "OneOffProductName": null
    },
    {
      "ProductPriceId": null,
      "Quantity": 2,
      "OneOffProductAmount": 10,
      "OneOffProductName": "Test one-time"
    }
  ],
  "Memo": "Thanks",
  "PaymentType": "NotifyUser",
  "PaymentGateways": ["Eft", "Interac", "VisaDirect"],
  "UserId": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
  "TaxRates": [],
  "CommonFees": []
}

Input parameters

Parameter	Type	Mandatory	Description
DaysToDueDate	int	yes	Days until due date
GenerateAsDraft	boolean	no	Set to true if you want this invoice to be generated has a draft
Memo	string	no	Memo that will be reflected on the transactions
PaymentType	string	yes	Payment type operator
UserId	guid	yes	Id for the user that will be charged for the invoice
PaymentGateways	string[]	yes	Payment gateways through witch the invoice will be processed
Items			ProductPrices that will be included on the invoice
OneOffProductAmount	decimal	yes (if product price is One-Off)	Amount for each unit or package
OneOffProductName	string	yes (if product price is One-Off)	Name for the one-off product
ProductPriceId	guid	yes (if is a normal product)	Id for the product price
Quantity	int	yes	Desired quantity for the product
TaxRates		no	Tax rates that will be included on the invoice
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 invoice
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

If you are creating a invoice with the AutomaticallyCharge Payment Type you should inform only one Payment Gateway

Response

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
TaxRates		Tax rates that will be included on the invoice
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 invoice
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 invoice#

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

Method: GET

Endpoint: {{env}}/api/invoice/{{invoice_id}}

Response

{
  "statusCode": 200,
  "message": "GET Request successful.",
  "isError": false,
  "result": {
    "Id": "5ef8f6f5-9c3e-436a-b018-3dbf4b11d21e",
    "UserId": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
    "User": {
      "Id": "59fb5f22-bbbf-404a-83f1-f86733afeb2f",
      "FirstName": " p17dyyno5390h97yt798pwe",
      "LastName": "Doe",
      "Email": "p17dyyno5390h97yt798pwe@zumrails.com",
      "IsActive": true
    },
    "CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
    "Customer": {
      "Id": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035",
      "CompanyName": "Sam's Gym"
    },
    "CreatedAt": "2022-02-15T12:26:09.299463",
    "Amount": 170,
    "InvoiceStatus": "Open",
    "Memo": "Thanks",
    "DaysToDueDate": 30,
    "DueDate": "2022-03-17T00:00:00",
    "PaymentType": "NotifyUser",
    "PaymentGateways": ["Eft", "Interac", "VisaDirect"],
    "Items": [
      {
        "Quantity": 2,
        "Currency": "CAD",
        "OneOffProductName": "Test one-time",
        "OneOffProductAmount": 10
      },
      {
        "ProductPrice": {
          "Id": "8a306490-21c2-44d9-bb61-4ee6bf4f4e8c",
          "ProductId": "b4518805-b310-448b-8d6c-20a55e22a61d",
          "CreatedAt": "2021-10-27T19:18:12.95601",
          "ProductPriceType": "Standard",
          "ProductPriceStatus": "Active",
          "Price": 150,
          "PerUnit": 0,
          "Frequency": "OneTime",
          "EnableFreeTrial": false,
          "FreeTrialInDays": 0,
          "EnableSetupFee": false,
          "SetupFee": 0,
          "Currency": "CAD",
          "Product": {
            "Id": "b4518805-b310-448b-8d6c-20a55e22a61d",
            "Name": "gym",
            "ProductStatus": "Active",
            "CustomerId": "e9a6db53-1c9b-491d-9ecb-cfb6c6f3d035"
          }
        },
        "ProductPriceId": "8a306490-21c2-44d9-bb61-4ee6bf4f4e8c",
        "Quantity": 1,
        "Currency": "CAD",
        "Price": 150
      }
    ],
    "Transactions": []
  }
}

Response

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

Search a invoice#

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.

Method: POST

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

Payload
Response

{
  "InvoiceStatus": 1,
  "UserName": "Test",
  "UserNameOperator": "contains",
  "DueDate": "2021-12-17T00:00:00.000Z",
  "DueDateOperator": "isInTheLast",
  "CreatedAt": "2021-12-02T03:00:00.000Z",
  "CreatedAtOperator": "exactlymatches",
  "GenericSearch": "Test",
  "Pagination": {
    "PageNumber": 1,
    "ItemsPerPage": 10
  }
}

Input parameters

Parameter	Type	Mandatory	Description
GenericSearch	string	no	Filter invoices by user name, user email or invoice id
InvoiceStatus	string	no	Invoice Status
CreatedAt	datetime	no	Create date
CreatedAtOperator	string	no	Operator to filter with CreatedAt properties
DueDate	datetime	no	Due date
DueDateOperator	string	no	Operator to filter with DueDate 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 invoices
Id	guid	The invoice Id
Amount	decimal	Total amount for the invoice
CreatedAt	date	Creation date for the invoice
DueDate	date	Due date
InvoiceStatus	string	Invoice status
ProductName	string	Name for the product related to invoice
User		User related to the invoice
FirstName	string	User first name
LastName	string	User last name
CompanyName	string	User Company
Email	string	User email
Id	guid	Id for the related user
IsActive	boolean	Indicates if the user is active or not

tip

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

Get invoice events#

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

Method: GET

Endpoint: {{env}}/api/invoice/getinvoiceevents/{{invoice_id}}

Response

{
  "statusCode": 200,
  "message": "GET Request successful.",
  "isError": false,
  "result": [
    {
      "CreatedAt": "2021-12-02T20:22:06.801874",
      "Description": "Invoice status has changed to Paid",
      "Type": "StatusChanged",
      "InvoiceId": "931940ab-0c94-4b52-b59c-9e32322a03a2"
    },
    {
      "CreatedAt": "2021-12-02T20:22:06.598206",
      "Description": "Transaction 724ceda1-f7fc-4832-b9d7-d5f74bc558a3 of 170 for this invoice was Completed",
      "Type": "TransactionStatusChanged",
      "InvoiceId": "931940ab-0c94-4b52-b59c-9e32322a03a2"
    },
    {
      "CreatedAt": "2021-12-02T20:21:24.229433",
      "Description": "Transaction 724ceda1-f7fc-4832-b9d7-d5f74bc558a3 of 170 for this invoice was InProgress",
      "Type": "TransactionStatusChanged",
      "InvoiceId": "931940ab-0c94-4b52-b59c-9e32322a03a2"
    },
    {
      "CreatedAt": "2021-12-02T20:14:04.971909",
      "Description": "Invoice 931940ab-0c94-4b52-b59c-9e32322a03a2 was created",
      "Type": "Created",
      "InvoiceId": "931940ab-0c94-4b52-b59c-9e32322a03a2"
    }
  ]
}

Response

A list of:

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

Invoice Event Type

Type	Behavior
Created	Invoice was created
Edited	Invoice was edited
SentToCustomer	Invoice was sended to customer
StatusChanged	Invoice status was changed
SentToUserWithForm	Invoice was sended to user (email of phone)
TransactionStatusChanged	Status for a transaction related to the invoice was changed

Modify invoice status#

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

Method: PATCH

Endpoint: {{env}}/api/invoice/changeinvoicestatus/{{invoice_id}}

info

Only invoices that have status Draft or Open can be changed through this method

Response

{
  "Status": "Paid"
}

Invoice Status

Type	Description
Paid	Invoice is paid
Void	Invoice is voided
Uncollectible	Invoice is uncollectible but can still be paid
Open	Invoice is open

Input parameters

Parameter	Type	Mandatory	Description
Status	string	yes	Status operator for invoice

Response

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