Invoices

Creating a new invoice#

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

Method: POST

Endpoint: {{env}}/api/invoice

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

Input parameters

ParameterTypeMandatoryDescription
DaysToDueDateintyesDays until due date
GenerateAsDraftbooleannoSet to true if you want this invoice to be generated has a draft
MemostringnoMemo that will be reflected on the transactions
PaymentTypestringyesPayment type operator
UserIdguidyesId for the user that will be charged for the invoice
PaymentGatewaysstring[]yesPayment gateways through witch the invoice will be processed
ItemsProductPrices that will be included on the invoice
OneOffProductAmountdecimalyes (if product price is One-Off)Amount for each unit or package
OneOffProductNamestringyes (if product price is One-Off)Name for the one-off product
ProductPriceIdguidyes (if is a normal product)Id for the product price
QuantityintyesDesired quantity for the product

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
info

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

Response

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
info

More info about transactions can be found here

Update a invoice#

caution

You can only update invoices that have Draft status

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

Method: PUT

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

Use this endpoint if you want to update a invoice.

Input parameters

ParameterTypeMandatoryDescription
DaysToDueDateintyesDays until due date
GenerateAsDraftbooleannoSet to true if you want this invoice to be generated has a draft
MemostringnoMemo that will be reflected on the transactions
PaymentTypestringyesPayment type operator
UserIdguidyesId for the user that will be charged for the invoice
PaymentGatewaysstring[]yesPayment gateways through witch the invoice will be processed
ItemsProductPrices that will be included on the invoice
OneOffProductAmountdecimalyes (if product price is One-Off)Amount for each unit or package
OneOffProductNamestringyes (if product price is One-Off)Name for the one-off product
ProductPriceIdguidyes (if is a normal product)Id for the product price
QuantityintyesDesired quantity for the product
info

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

Response

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

Get a specific invoice#

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

Method: GET

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

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

Response

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

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.

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

Method: POST

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

Input parameters

ParameterTypeMandatoryDescription
GenericSearchstringnoFilter invoices by user name, user email or invoice id
InvoiceStatusstringnoInvoice Status
CreatedAtdatetimenoCreate date
CreatedAtOperatorstringnoOperator to filter with CreatedAt properties
DueDatedatetimenoDue date
DueDateOperatorstringnoOperator to filter with DueDate 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 invoices
IdguidThe invoice Id
AmountdecimalTotal amount for the invoice
CreatedAtdateCreation date for the invoice
DueDatedateDue date
InvoiceStatusstringInvoice status
ProductNamestringName for the product related to invoice
UserUser related to the invoice
FirstNamestringUser first name
LastNamestringUser last name
CompanyNamestringUser Company
EmailstringUser email
IdguidId for the related user
IsActivebooleanIndicates 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#

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

Method: GET

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

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

Response

A list of:

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

Invoice Event Type

TypeBehavior
CreatedInvoice was created
EditedInvoice was edited
SentToCustomerInvoice was sended to customer
StatusChangedInvoice status was changed
SentToUserWithFormInvoice was sended to user (email of phone)
TransactionStatusChangedStatus for a transaction related to the invoice was changed

Modify invoice status#

info

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

{
"SecurityPassword": "your_password",
"Status": "Paid"
}

Method: PATCH

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

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

Invoice Status

TypeDescription
PaidInvoice is paid
VoidInvoice is voided
UncollectibleInvoice is uncollectible but can still be paid
OpenInvoice is open

Input parameters

ParameterTypeMandatoryDescription
StatusstringyesStatus operator for invoice
SecurityPasswordstringyesYou password

Response

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