Bills

Get all bills

Returns all bills, optionally filtered by customers, identifiers and other filters. Note this operation uses Pagination.

Request

[PlatformAddress]/api/connector/v1/bills/getAll

{
  "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
  "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
  "Client": "Sample Client 1.0.0",
  "Extent": {
    "Items": false
  },
  "TimeFilter": null,
  "StartUtc": null,
  "EndUtc": null,
  "ClosedUtc": {
    "StartUtc": "2020-02-05T00:00:00Z",
    "EndUtc": "2020-02-10T00:00:00Z"
  },
  "PaidUtc": null,
  "DueUtc": null,
  "CreatedUtc": {
    "StartUtc": "2020-02-05T00:00:00Z",
    "EndUtc": "2020-02-10T00:00:00Z"
  },
  "UpdatedUtc": {
    "StartUtc": "2020-02-05T00:00:00Z",
    "EndUtc": "2020-02-10T00:00:00Z"
  },
  "BillIds": [
    "e654f217-d1b5-46be-a820-e93ba568dfac"
  ],
  "CustomerIds": [
    "fe795f96-0b64-445b-89ed-c032563f2bac"
  ],
  "State": "Closed",
  "CorrectionState": null,
  "EnterpriseIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "4d0201db-36f5-428b-8d11-4f0a65e960cc"
  ],
  "Limitation": {
    "Count": 100,
    "Cursor": "e7f26210-10e7-462e-9da8-ae8300be8ab7"
  }
}

Property	Type	Contract	Description
ClientToken	string	required	Token identifying the client application.
AccessToken	string	required	Access token of the client application.
Client	string	required	Name and version of the client application.
EnterpriseIds	array of string	optional, max 1000 items	Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token.
ClosedUtc	Time interval	optional, max length 3 months	Interval in which the Bill was closed.
PaidUtc	Time interval	optional, max length 3 months	Interval in which the Bill was paid.
DueUtc	Time interval	optional, max length 3 months	Interval in which the Bill is due to be paid.
CreatedUtc	Time interval	optional, max length 3 months	Interval in which the Bill was created.
UpdatedUtc	Time interval	optional, max length 3 months	Interval in which the Bill was updated.
BillIds	array of string	optional, max 1000 items	Unique identifiers of the Bills. Required if no other filter is provided.
CustomerIds	array of string	optional, max 1000 items	Unique identifiers of the Customers.
State	Bill state	required	State the bills should be in. If not specified, Open and Closed bills are returned.
CorrectionState	array of Bill correction state	optional	Whether to return regular bills, corrective bills, or both. If BillIds are specified, defaults to both, otherwise defaults to Bill.
Limitation	Limitation	required	Limitation on the quantity of data returned.
Extent	Bill extent	optional	Extent of data to be returned. E.g. it is possible to specify that together with the bills, payments and revenue items should be also returned. Deprecated! Use orderItems/getAll and payments/getAll with BillIds filter instead.

Bill extent

Extent of data to be returned. E.g. it is possible to specify that together with the bills, payments and revenue items should be also returned. Deprecated!

Property	Type	Contract	Description
Items	boolean	required	Whether the response should contain payments and revenue items. Deprecated! Use orderItems/getAll and payments/getAll with BillIds filter instead.

Response

{
  "Bills": [
    {
      "Id": "26afba60-06c3-455b-92db-0e3983be0b1d",
      "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "AccountId": "fe795f96-0b64-445b-89ed-c032563f2bac",
      "CustomerId": null,
      "CompanyId": null,
      "AssociatedAccountIds": [
        "26afba60-06c3-455b-92db-0e3983be0b1d"
      ],
      "CounterId": null,
      "State": "Closed",
      "Type": "Invoice",
      "Number": "29",
      "VariableSymbol": null,
      "CreatedUtc": "2017-01-31T10:48:06Z",
      "IssuedUtc": "2017-01-31T10:58:06Z",
      "TaxedUtc": null,
      "PaidUtc": null,
      "DueUtc": null,
      "UpdatedUtc": "2017-01-31T10:58:06Z",
      "PurchaseOrderNumber": "XX-123",
      "Notes": "",
      "Options": {
        "DisplayCustomer": true,
        "DisplayTaxation": true,
        "TrackReceivable": true,
        "DisplayCid": false,
        "Rebated": false
      },
      "Revenue": [],
      "Payments": [],
      "OrderItems": [],
      "PaymentItems": [],
      "AssigneeData": null,
      "OwnerData": {
        "Discriminator": "BillCompanyData",
        "Value": {
          "Id": "26afba60-06c3-455b-92db-0e3983be0b1d",
          "Address": {
            "Line1": "Joe Doe street",
            "Line2": "Very long ave",
            "City": "Townston",
            "PostalCode": "154 00",
            "SubdivisionCode": "AU-NSW",
            "CountryCode": "AU"
          },
          "LegalIdentifiers": {
            "TaxIdentifier": "CZ8810310963",
            "CityOfRegistration": "Prague"
          },
          "BillingCode": "Billing code value",
          "Name": "Acme, Inc.",
          "FiscalIdentifier": "Fiscal identifier",
          "AdditionalTaxIdentifier": "Additional tax identifier"
        }
      },
      "CompanyDetails": null,
      "AssociatedAccountData": [
        {
          "Discriminator": "BillCompanyData",
          "BillCustomerData": null,
          "BillCompanyData": {
            "Id": "26afba60-06c3-455b-92db-0e3983be0b1d",
            "Address": {
              "Line1": "Joe Doe street",
              "Line2": "Very long ave",
              "City": "Townston",
              "PostalCode": "154 00",
              "SubdivisionCode": "AU-NSW",
              "CountryCode": "AU"
            },
            "LegalIdentifiers": {
              "TaxIdentifier": "CZ8810310963",
              "CityOfRegistration": "Prague"
            },
            "BillingCode": "Billing code value",
            "Name": "Acme, Inc.",
            "FiscalIdentifier": "Fiscal identifier",
            "AdditionalTaxIdentifier": "Additional tax identifier"
          }
        }
      ],
      "EnterpriseData": {
        "AdditionalTaxIdentifier": "XY00112233445",
        "CompanyName": "The Sample Hotel Group AS",
        "BankAccount": "CZ3808000000000012345678",
        "BankName": "CESKA SPORITELNA A.S.",
        "Iban": "CZ6508000000192000145399",
        "Bic": "GIBACZPX"
      },
      "CorrectionState": "Bill",
      "CorrectionType": null,
      "CorrectedBillId": null
    }
  ],
  "Cursor": "26afba60-06c3-455b-92db-0e3983be0b1d"
}

Property	Type	Contract	Description
Bills	array of Bill	required	The filtered bills.
Cursor	string	optional	Unique identifier of the last and hence oldest bill returned. This can be used in Limitation in a subsequent request to fetch the next batch of older bills.

Bill

Property	Type	Contract	Description
Id	string	required	Unique identifier of the bill.
EnterpriseId	string	required	Unique identifier of the Enterprise.
AccountId	string	required	Unique identifier of the account (Customer or Company) the bill is issued to.
AssociatedAccountIds	array of string	optional	Unique identifiers of the Customers or Companies that are associated to the bill.
CounterId	string	optional	Unique identifier of the bill Counter.
State	Bill state	required	Whether the bill is Open or Closed.
Type	Bill type	required	After a bill is closed, the Bill Type is set to Receipt or Invoice. Receipt indicates that the bill has been fully paid and the balance is zero. Invoice indicates that the bill has not yet been fully paid but an invoice has been issued. Prior to closing, Bill Type should not be used.
Number	string	optional	Number of the bill.
VariableSymbol	string	optional	Variable symbol of the bill.
CreatedUtc	string	required	Date and time of the bill creation in UTC timezone in ISO 8601 format.
IssuedUtc	string	optional	Date and time of the bill issuance in UTC timezone in ISO 8601 format.
TaxedUtc	string	optional	Taxation date of the bill in UTC timezone in ISO 8601 format.
PaidUtc	string	optional	Date when the bill was paid in UTC timezone in ISO 8601 format.
DueUtc	string	optional	Bill due date and time in UTC timezone in ISO 8601 format.
UpdatedUtc	string	required	Date and time when the bill was last updated, in UTC timezone in ISO 8601 format.
PurchaseOrderNumber	string	optional	Unique number of the purchase order from the buyer.
Notes	string	optional	Additional notes.
Options	Bill options	optional	Options of the bill.
OwnerData	Bill owner data	required	Additional information about owner of the bill. Can be a Customer or Company. Persisted at the time of closing of the bill.
AssociatedAccountData	array of Associated account bill data	optional	Additional information about the associated account of the bill. Can be a Customer or Company. Persisted at the time of closing of the bill. Currently only one account can be associated with a bill, but this may be extended in future.
EnterpriseData	Bill enterprise data	optional	Additional information about the enterprise issuing the bill, including bank account details. Persisted at the time of closing of the bill.
CorrectionState	Bill correction state	required	Whether the bill is a regular bill or a corrective bill.
CorrectionType	Bill correction type	optional	Type of correction.
CorrectedBillId	string	optional	The ID of the bill that the corrective bill corrects. If the corrected bill was deleted, this field is null.
CustomerId	string	optional	Unique identifier of the Customer the bill is issued to. Deprecated! Use AccountId instead.
CompanyId	string	optional	Unique identifier of the Company specified in CompanyDetails or the Company the bill is issued to. Deprecated! Use AssociatedAccountIds instead.
Revenue	array of Accounting item	optional	Deprecated! Use orderItems/getAll with BillId instead.
Payments	array of Accounting item	optional	Deprecated! Use payments/getAll with BillId instead.
OrderItems	array of Order item	optional	The order items (consumed items such as nights or products) on the bill. Deprecated! Use orderItems/getAll with BillId instead.
PaymentItems	array of Payment item	optional	The payment items (such as cash, credit card payments or invoices) on the bill. Deprecated!
AssigneeData	Bill assignee data	required	Deprecated! Use OwnerData instead.
CompanyDetails	Bill company data	optional	Additional information about the company assigned to the bill. Not the same as the owner. Persisted at the time of closing of the bill. Deprecated! Use AssociatedAccountData instead.

Bill state

• Open

• Closed

Bill type

• Receipt - Default; the bill has been paid in full; only applicable after the bill is closed.

• Invoice - Bill has not been paid in full but an invoice has been issued to request payment.

Bill options

Options of the bill.

Property	Type	Contract	Description
DisplayCustomer	boolean	required	Display customer information on a bill.
DisplayTaxation	boolean	required	Display taxation detail on a bill.
TrackReceivable	boolean	required	Tracking of payments is enabled for bill, only applicable for BillType of Invoice.
DisplayCid	boolean	required	Display CID number on bill, only applicable for BillType of Invoice.
Rebated	boolean	required	Whether the bill is rebated (both fully or partially).

Bill assignee data

Property	Type	Contract	Description
Discriminator	Bill associated account data discriminator	required	Determines type of value.
Value	object	required	Structure of object depends on Discriminator.

Bill associated account data discriminator

• BillCustomerData

• BillCompanyData

Bill company data

Property	Type	Contract	Description
Id	string	optional	ID of the Company.
Address	Address	optional	Address of the company.
LegalIdentifiers	object	optional	The set of LegalIdentifiers for the company.
BillingCode	string	optional	A unique code for Mews to list on invoices it sends to the company.
Name	string	required	Name of the company.
FiscalIdentifier	string	optional	Fiscal identifier of the company.
AdditionalTaxIdentifier	string	optional	Additional tax identifier of the company.

Bill customer data

Property	Type	Contract	Description
Id	string	required	ID of the Customer to whom the bill was assigned.
Address	Address	optional	Address of the customer.
LegalIdentifiers	object	optional	The set of LegalIdentifiers for the customer.
BillingCode	string	optional	A unique code for Mews to list on invoices it sends to the customer.
LastName	string	required	Last name of the customer.
FirstName	string	optional	First name of the customer.
SecondLastName	string	optional	Second last name of the customer.
TitlePrefix	Title	required	Title prefix of the customer.

Bill owner data

Additional information about owner of the bill. Can be a Customer or Company. Persisted at the time of closing of the bill.

Property	Type	Contract	Description
Discriminator	Bill associated account data discriminator	required	Determines type of value.
Value	object	required	Structure of object depends on Discriminator.

Associated account bill data

Property	Type	Contract	Description
Discriminator	Bill associated account data discriminator	required	Determines type of value.
BillCustomerData	Bill customer data	optional	Associated account bill data for customer.
BillCompanyData	Bill company data	optional	Associated account bill data for company.

Bill enterprise data

Additional information about the enterprise issuing the bill, including bank account details. Persisted at the time of closing of the bill.

Property	Type	Contract	Description
AdditionalTaxIdentifier	string	optional	Enterprise additional tax identifier.
CompanyName	string	optional	Enterprise company name.
BankAccount	string	optional	Enterprise bank account.
BankName	string	optional	Enterprise bank name.
Iban	string	optional	Enterprise IBAN (International Bank Account Number).
Bic	string	optional	Enterprise BIC (Bank Identifier Code).

Bill correction state

• Bill - Regular bill.

• CorrectiveBill - Corrective bill, i.e. the CorrectionType is either Edit, Cancellation, or ReceivablePaymentsBalance.

Bill correction type

• Cancellation

• Edit

• CreditNote

• Reinstatement

• ReceivablePaymentsBalance

Get bill PDF

Creates a PDF version of the specified bill. In case it's not possible to return PDF immediately, you must retry the call later while providing the unique event identifier that is returned from the first invocation.

Request

[PlatformAddress]/api/connector/v1/bills/getPdf

{
  "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
  "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
  "Client": "Sample Client 1.0.0",
  "BillId": "44eba542-193e-47c7-8077-abd7008eb206",
  "BillPrintEventId": null
}

Property	Type	Contract	Description
ClientToken	string	required	Token identifying the client application.
AccessToken	string	required	Access token of the client application.
Client	string	required	Name and version of the client application.
BillId	string	required	Unique identifier of the Bill to be printed.
BillPrintEventId	string	optional	Unique identifier of the Bill print event returned by previous invocation.

Response

{
  "BillId": "44eba542-193e-47c7-8077-abd7008eb206",
  "Result": {
    "Discriminator": "BillPdfFile",
    "Value": {
      "Base64Data": "JVBERi0xLj..."
    }
  }
}

Property	Type	Contract	Description
BillId	string	required	Unique identifier of the printed bill.
Result	Bill PDF result discriminator	required

Bill PDF result discriminator

Property	Type	Contract	Description
Discriminator	Bill PDF result discriminator	required	Determines type of value.
Value	object	required	Structure of object depends on Discriminator.

Bill PDF result discriminator

• BillPdfFile - PDF version of a Bill was successfully created, Value is BillPdfFile.

• BillPrintEvent - PDF version of a Bill couldn't be created at this moment (for example bill haven't been reported to authorities yet), Value is BillPrintEvent

Bill PDF file

Property	Type	Contract	Description
Base64Data	string	required	Base64 encoded PDF file.

Bill print event

Property	Type	Contract	Description
BillPrintEventId	string	required	Unique identifier of print event. Must be used in retry calls to retrieve the PDF.

Add bill

Creates new empty bill assigned to specified account. Note this operation supports Portfolio Access Tokens.

Request

[PlatformAddress]/api/connector/v1/bills/add

{
  "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
  "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
  "Client": "Sample Client 1.0.0",
  "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Bills": [
    {
      "AccountId": "a5786a7b-a388-43cc-a838-abd7007b5ff7",
      "Name": "Bill of Joe Doe"
    }
  ]
}

Property	Type	Contract	Description
ClientToken	string	required	Token identifying the client application.
AccessToken	string	required	Access token of the client application.
Client	string	required	Name and version of the client application.
EnterpriseId	string	optional	Unique identifier of the enterprise. Required when using Portfolio Access Tokens, ignored otherwise.
Bills	array of Bill parameters	required, max 1000 items	Information about bills to be created.

Bill parameters

Property	Type	Contract	Description
AccountId	string	required	Unique identifier of the account (Customer or Company) the bill is issued to. Company billing may not be enabled for your integration.
AssociatedAccountId	string	optional	Account that has a possible link with the owner of the bill.
Name	string	optional	Name of the newly created bill.

Response

{
  "BillId": "44eba542-193e-47c7-8077-abd7008eb206",
  "Result": {
    "Discriminator": "BillPdfFile",
    "Value": {
      "Base64Data": "JVBER....."
    }
  }
}

Property	Type	Contract	Description
Bills	array of Bill	required	The created bills.

Delete bill

Removes selected bills. Bill must be empty, otherwise it's not possible to delete it. Note this operation supports Portfolio Access Tokens.

Request

[PlatformAddress]/api/connector/v1/bills/delete

{
  "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
  "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
  "Client": "Sample Client 1.0.0",
  "BillIds": [
    "177966b7-f3d9-42b7-ba49-abd80057329b"
  ],
  "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Property	Type	Contract	Description
ClientToken	string	required	Token identifying the client application.
AccessToken	string	required	Access token of the client application.
Client	string	required	Name and version of the client application.
EnterpriseId	string	optional	Unique identifier of the enterprise. Required when using Portfolio Access Tokens, ignored otherwise.
BillIds	array of string	required, max 1000 items	Unique identifiers of the Bills to be deleted.

Response

{}

Close bill

Closes a bill so no further modification to it is possible. Note this operation supports Portfolio Access Tokens.

Request

[PlatformAddress]/api/connector/v1/bills/close

{
  "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
  "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
  "Client": "Sample Client 1.0.0",
  "BillId": "44eba542-193e-47c7-8077-abd7008eb206",
  "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Type": "Receipt",
  "BillCounterId": "84b25778-c1dd-48dc-8c00-ab3a00b6df14",
  "FiscalMachineId": null,
  "Options": {
    "DisplayCustomer": {
      "Value": false
    },
    "DisplayTaxation": null
  },
  "TaxedDate": {
    "Value": "2020-07-07"
  },
  "DueDate": {
    "Value": "2020-07-14"
  },
  "VariableSymbol": {
    "Value": "5343"
  },
  "AccountTaxIdentifier": {
    "Value": "446768"
  },
  "AccountAddress": {
    "Line1": "Astronautů 2",
    "Line2": "",
    "City": "Havířov",
    "PostalCode": "736 01",
    "CountryCode": "CZ",
    "CountrySubdivisionCode": null
  },
  "PurchaseOrderNumber": {
    "Value": "XX-123"
  },
  "Notes": {
    "Value": "Bill closing note"
  },
  "AssociatedAccountData": [
    {
      "Id": "84b25778-c1dd-48dc-8c00-ab3a00b6df14",
      "TaxIdentifier": {
        "Value": "123459"
      },
      "Address": {
        "Line1": "Astronautů 2",
        "Line2": "",
        "City": "Havířov",
        "PostalCode": "736 01",
        "CountryCode": "CZ",
        "CountrySubdivisionCode": null
      }
    }
  ]
}

Property	Type	Contract	Description
ClientToken	string	required	Token identifying the client application.
AccessToken	string	required	Access token of the client application.
Client	string	required	Name and version of the client application.
EnterpriseId	string	optional	Unique identifier of the enterprise. Required when using Portfolio Access Tokens, ignored otherwise.
BillId	string	required	Unique identifier of the Bill to be closed.
Type	Bill type	required	After a bill is closed, the Bill Type is set to Receipt or Invoice. Receipt indicates that the bill has been fully paid and the balance is zero. Invoice indicates that the bill has not yet been fully paid but an invoice has been issued. Prior to closing, Bill Type should not be used.
BillCounterId	string	optional	Unique identifier of the Counter to be used for closing. Default one is used when no value is provided.
FiscalMachineId	string	optional	Unique identifier of the Fiscal Machine to be used for closing. Default one is used when no value is provided.
Options	Bill options parameters	optional	Options of the bill. If not provided, both DisplayCustomer and DisplayTaxation are set by default.
TaxedDate	String update value	optional	Date of consumption for tax purposes. Can be used only with Type of Invoice.
DueDate	String update value	optional	Deadline when bill is due to be paid. Can be used only with Type of Invoice.
VariableSymbol	String update value	optional	Optional unique identifier of requested payment. Can be used only with Type of Invoice.
AccountTaxIdentifier	String update value	optional	Tax identifier of account to be put on a bill.
PurchaseOrderNumber	String update value	optional	Unique number of the purchase order from the buyer.
Notes	String update value	optional	Notes to be attached to bill.
AccountAddress	Address parameters	optional	Address of the account to be displayed on bill. Overrides the default one taken from account profile.
AssociatedAccountData	array of Bill close account parameters	optional, max 1 item	Account data of the associated account on a bill. Currently one object is supported and only populated when the bill is closed.
TaxIdentifier	String update value	optional	Tax identifier of account to be put on a bill. Deprecated! Use AccountTaxIdentifier or AssociatedAccountData instead.
CompanyTaxIdentifier	String update value	optional	Tax identifier of company to be put on a bill. Deprecated! Use AccountTaxIdentifier or AssociatedAccountData instead.
Address	Address parameters	optional	Address of the account to be displayed on bill. Overrides the default one taken from account profile. Deprecated! Use AccountAddress or AssociatedAccountData instead.

Bill options parameters

Property	Type	Contract	Description
DisplayCustomer	Bool update value	required	Display customer information on a bill.
DisplayTaxation	Bool update value	required	Display taxation detail on a bill.

Bill close account parameters

Property	Type	Contract	Description
Id	string	required	Unique identifier of the associated account (Customer or Company) the bill is associated to.
TaxIdentifier	String update value	optional	Tax identifier of the associated account to be put on a bill.
Address	Address parameters	optional	Address of the associated account to be displayed on bill. Overrides the default one taken from account profile.

Response

{
  "BillId": "44eba542-193e-47c7-8077-abd7008eb206",
  "Result": {
    "Discriminator": "BillPdfFile",
    "Value": {
      "Base64Data": "JVBER....."
    }
  }
}

Property	Type	Contract	Description
Bills	array of Bill	required	The closed bills.