Log In Sign up
API Docs OAuth Clients Access Tokens

Invoices

GET https://subdomain.cobot.me/api/invoices

Returns all invoices for a space (when user is admin) or member (when user is member).

Authentication required:
yes, additionally user must be a space admin or member
Scope required:
read_invoices
GET https://co-up.cobot.me/api/invoices

Optionally you can supply from and to parameters to only return invoices issued between dates.

GET https://co-up.cobot.me/api/invoices?from=2013-02-01&to=2013-02-28

Or you can supply a list of invoice ids separated by commas:

GET https://co-up.cobot.me/api/invoices?ids=cc7e75473a6911587b63d78f4e3f8eba

Response:

[
  {
    "created_at": "2012/01/01",
    "paid_at": null,
    "charge_at": "2012/01/02 12:00:00 +0000",
    "due_date": "2012/01/01",
    "currency": "EUR",
    "id": "cc7e75473a6911587b63d78f4e3f8eba",
    "membership_id": "a9f6bcbed420c37539fa1257e66fd66b",
    "contact_id": null,
    "address": {
      "name": "joe doe",
      "full_address": "broadway\n12345 Berlin",
      "company": "joe inc.",
      "country": "ocean"
    },
    "space_address": {
      "name": "john space",
      "full_address": "2 coworking way\n37521 new atlantis",
      "company": "space inc.",
      "country": "oceanis"
    },
    "invoice_text": "pay now",
    "tax_name": "VAT",
    "tax_id_name": "VAT ID",
    "tax_id": "100-535-87D",
    "invoice_number": 100,
    "formatted_invoice_number": "2016-X-100",
    "customer_number": 101,
    "items": [
      {
        "id": "53d3fc2107436",
        "paid": false,
        "amount": "80.0",
        "description": "monthly rent",
        "quantity": "2.0",
        "tax_rate": "20.0",
        "tax_amount": "16.0",
        "amount_with_tax": "96.0",
        "total_amount": "160.0",
        "total_amount_with_tax": "192.0",
        "total_tax_amount": "32.0",
        "accounting_code": "FlexPlan",
        "cost_center": null,
        "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
      },
      {
        "id": "53d3fc2107438",
        "paid": false,
        "amount": "20.0",
        "description": "2 time passes",
        "quantity": "2.0",
        "tax_rate": "20.0",
        "tax_amount": "4.0",
        "amount_with_tax": "24.0",
        "total_amount": "40.0",
        "total_amount_with_tax": "48.0",
        "total_tax_amount": "8.0",
        "accounting_code": "Pass",
        "cost_center": null,
        "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
      }
    ],
    "total_amount": "250.0",
    "total_amount_without_taxes": "200.0",
    "payable_amount": "250.0",
    "total_paid_amount": "0.0",
    "taxes": [
      { "name": "VAT", "rate": "20.0", "amount": "40.0" },
      { "name": "TPS", "rate": "5.0", "amount": "10.0" }
    ],
    "url": "http://some-space.cobot.me/api/invoices/100",
    "paid": false,
    "sent": false,
    "sent_status": "unsent",
    "paid_status": "unpaid",
    "can_charge": true,
    "can_update": true
  }
]

You can append .zip to the url to get the invoices as single page PDFs in a zip file. File names in the zip file will be {space_name}_invoice_{invoice number}.pdf

GET https://:subdomain.cobot.me/api/invoices/:id

Returns a single invoice for a space.

Authentication required:
yes, additionally user must be a space admin
Scope required:
read_invoices
GET https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba

Response:

{
  "created_at": "2012-01-01",
  "paid_at": null,
  "charge_at": "2012/01/02 12:00:00 +0000",
  "due_date": "2012/01/01",
  "currency": "EUR",
  "id": "cc7e75473a6911587b63d78f4e3f8eba",
  "membership_id": "a9f6bcbed420c37539fa1257e66fd66b",
  "contact_id": null,
  "address": {
    "name": "joe doe",
    "full_address": "broadway\n12345 Berlin",
    "company": "joe inc.",
    "country": "ocean"
  },
  "space_address": {
    "name": "john space",
    "address": "2 coworking way\n37521 new atlantis",
    "company": "space inc.",
    "country": "oceanis"
  },
  "invoice_text": "pay now",
  "tax_name": "VAT",
  "tax_id_name": "VAT ID",
  "tax_id": "100-535-87D",
  "invoice_number": 100,
  "formatted_invoice_number": "2016-X-100",
  "customer_number": 101,
  "items": [
    {
      "id": "53d3fc2107436",
      "paid": false,
      "amount": "80.0",
      "description": "monthly rent",
      "quantity": "2.0",
      "tax_rate": "20.0",
      "tax_amount": "16.0",
      "amount_with_tax": "96.0",
      "total_amount": "160.0",
      "total_amount_with_tax": "192.0",
      "total_tax_amount": "32.0",
      "accounting_code": "FlexPlan",
      "cost_center": {
        "name": "Plans",
        "number": "P1"
      },
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    },
    {
      "id": "53d3fc2107437",
      "paid": false,
      "amount": "20.0",
      "description": "2 time passes",
      "quantity": "2.0",
      "tax_rate": "20.0",
      "tax_amount": "4.0",
      "amount_with_tax": "24.0",
      "total_amount": "40.0",
      "total_amount_with_tax": "48.0",
      "total_tax_amount": "8.0",
      "accounting_code": "Pass",
      "cost_center": {
        "name": "Time Passes",
        "number": "TP1"
      },
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    }
  ],
  "total_amount": "240.0",
  "total_amount_without_taxes": "200.0",
  "payable_amount": "240.0",
  "total_paid_amount": "0.0",
  "taxes": [{ "name": "VAT", "rate": "20.0", "amount": "40.0" }],
  "url": "http://some-space.cobot.me/api/invoices/100",
  "paid": false,
  "sent": false,
  "sent_status": "unsent",
  "paid_status": "unpaid",
  "can_charge": true,
  "can_update": true,
  "remind_at": "2012-01-15",
  "last_reminder_sent_at": "2012/01/16 09:15:00 +0000",
  "sent_reminders_count": 1
}
paid_at
Date the invoice was marked as paid.
charge_at
The time Cobot will try to collect the invoice. This can be empty if no collection is scheduled.
can_charge
Whether there is an automated payment method available to charge the invoice.
can_update
Whether users can still update the invoice or its items manually (turns false after an invoice is locked).

By default the invoice items that have no tax rate set will be returned with the invoice tax rate filled in. Optionally you can supply a fill_in_item_tax_rate=false parameter to return null item tax rates.

GET https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba?fill_in_item_tax_rate=false

You can append .pdf to the url to get the invoice as a pdf document.

GET https://:subdomain.cobot.me/api/invoices/open
Authentication required:
yes, additionally user must be a space admin
Scope required:
read_invoices

Returns a list of open invoices. The results look the same as the list of invoices above.

GET https://:subdomain.cobot.me/api/memberships/:membership_id/invoices

Optionally you can supply from/to parameters to only list invoices for a certain timespan.

Authentication required:
yes, additionally user must be a space admin
Scope required:
read_invoices

Returns a list of invoices. The results look the same as the list of invoices above.

POST https://:subdomain.cobot.me/api/memberships/:membership_id/charges_based_invoices

Creates an invoice that contains all current charges for a member. When this invoice is created the charges will not be included again in the next auto generated invoice.

Authentication required:
yes, additionally user must be a space admin.
Scope required:
write_invoices
POST https://co-up.cobot.me/api/memberships/a9f6bcbed420c37539fa1257e66fd66b/charges_based_invoices

Response:

{
  "created_at": "2012/01/01",
  "paid_at": null,
  "charge_at": null,
  "due_date": "2012/01/01",
  "currency": "EUR",
  "id": "cc7e75473a6911587b63d78f4e3f8eba",
  "membership_id": "a9f6bcbed420c37539fa1257e66fd66b",
  "contact_id": null,
  "address": {
    "name": "joe doe",
    "full_address": "broadway\n12345 Berlin",
    "company": "joe inc.",
    "country": "ocean"
  },
  "space_address": {
    "name": "john space",
    "address": "2 coworking way\n37521 new atlantis",
    "company": "space inc.",
    "country": "oceanis"
  },
  "invoice_text": "pay now",
  "tax_name": "VAT",
  "tax_id_name": "VAT ID",
  "tax_id": "100-535-87D",
  "invoice_number": 100,
  "formatted_invoice_number": "2016-X-100",
  "customer_number": 101,
  "items": [
    {
      "id": "53d3fc2107436",
      "paid": false,
      "amount": "1.0",
      "description": "cup of coffee",
      "quantity": "200.0",
      "tax_rate": "20.0",
      "tax_amount": "0.2",
      "amount_with_tax": "1.2",
      "total_amount": "200.0",
      "total_amount_with_tax": "240.0",
      "total_tax_amount": "40.0",
      "accounting_code": "Coffee",
      "cost_center": null,
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    }
  ],
  "total_amount": "240.0",
  "total_amount_without_taxes": "200.0",
  "payable_amount": "240.0",
  "total_paid_amount": "0.0",
  "taxes": [{ "name": "VAT", "rate": "20.0", "amount": "40.0" }],
  "url": "http://some-space.cobot.me/api/invoices/100",
  "paid": false,
  "sent": false,
  "sent_status": "unsent",
  "paid_status": "unpaid",
  "can_charge": true
}

Responds with status 201 and the invoice on success, 422 if no open charges exist for the member.

POST https://:subdomain.cobot.me/api/memberships/:membership_id/invoices

Creates an invoice for a member.

Authentication required:
yes, additionally user must be a space admin or member (members can only create invoices for themselves)
Scope required:
write_invoices
POST https://co-up.cobot.me/api/memberships/a9f6bcbed420c37539fa1257e66fd66b/invoices

Body:

{
  "currency": "EUR",
  "invoice_text": "pay now",
  "notes": "sample note",
  "created_at": "20/07/2017",
  "address": {
    "name": "Joe Doe",
    "company": "Joe Inc."
  },
  "items": [
    {
      "amount": "1.0",
      "description": "cup of coffee",
      "quantity": "200",
      "tax_rate": "20.0",
      "tax_amount": "0.2",
      "amount_with_tax": "2.2",
      "total_amount": "200.0",
      "total_amount_with_tax": "240.0",
      "total_tax_amount": "40.0",
      "accounting_code": "beverages",
      "cost_center": {
        "name": "extras",
        "number": "BEV1"
      }
    }
  ]
}

Required attributes:

  • items
  • amount
  • description

Response:

{
  "created_at": "2012/01/01",
  "paid_at": null,
  "charge_at": null,
  "due_date": "2012/01/01",
  "currency": "EUR",
  "id": "cc7e75473a6911587b63d78f4e3f8eba",
  "membership_id": "a9f6bcbed420c37539fa1257e66fd66b",
  "contact_id": null,
  "address": {
    "name": "Joe Doe",
    "full_address": "broadway\n12345 Berlin",
    "company": "Joe Inc.",
    "country": "ocean"
  },
  "space_address": {
    "name": "john space",
    "address": "2 coworking way\n37521 new atlantis",
    "company": "space inc.",
    "country": "oceanis"
  },
  "invoice_text": "pay now",
  "tax_name": "VAT",
  "tax_id_name": "VAT ID",
  "tax_id": "100-535-87D",
  "invoice_number": 100,
  "formatted_invoice_number": "2016-X-100",
  "customer_number": 101,
  "items": [
    {
      "id": "53d3fc2107436",
      "paid": false,
      "amount": "1.0",
      "description": "cup of coffee",
      "quantity": "200.0",
      "tax_rate": "20.0",
      "tax_amount": "0.2",
      "amount_with_tax": "1.2",
      "total_amount": "200.0",
      "total_amount_with_tax": "240.0",
      "total_tax_amount": "40.0",
      "accounting_code": "Coffee",
      "cost_center": {
        "name": "extras",
        "number": "BEV1"
      },
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    }
  ],
  "total_amount": "240.0",
  "total_amount_without_taxes": "200.0",
  "payable_amount": "240.0",
  "total_paid_amount": "0.0",
  "taxes": [{ "name": "VAT", "rate": "20.0", "amount": "40.0" }],
  "url": "http://some-space.cobot.me/api/invoices/100",
  "paid": false,
  "sent": false,
  "sent_status": "unsent",
  "paid_status": "unpaid",
  "can_charge": true
}

POST https://:subdomain.cobot.me/api/invoices

Creates an invoice for a non-member.

Authentication required:
yes, additionally user must be a space admin or member (members can only create invoices for themselves)
Scope required:
write_invoices
POST https://co-up.cobot.me/api/invoices

Body:

{
  "currency": "EUR",
  "invoice_text": "pay now",
  "notes": "sample note",
  "created_at": "20/07/2017",
  "billing_email": "billing@acme.com jane@doe.com",
  "address": {
    "name": "Joe Doe",
    "company": "Joe Inc.",
    "full_address": "broadway\n12345 Berlin",
    "country": "ocean"
  },
  "items": [
    {
      "amount": "1.0",
      "description": "cup of coffee",
      "quantity": "200",
      "tax_rate": "20.0",
      "tax_amount": "0.2",
      "amount_with_tax": "1.2",
      "total_amount": "200.0",
      "total_amount_with_tax": "240.0",
      "total_tax_amount": "40.0",
      "accounting_code": "beverages"
    }
  ]
}

Required attributes:

  • items
    • amount
    • description
  • address
    • name or company

Response:

{
  "created_at": "2012/01/01",
  "paid_at": null,
  "charge_at": null,
  "due_date": "2012/01/01",
  "currency": "EUR",
  "id": "cc7e75473a6911587b63d78f4e3f8eba",
  "billing_emails": ["billing@acme.com", "jane@doe.com"],
  "address": {
    "name": "Joe Doe",
    "full_address": "broadway\n12345 Berlin",
    "company": "Joe Inc.",
    "country": "ocean"
  },
  "space_address": {
    "name": "john space",
    "address": "2 coworking way\n37521 new atlantis",
    "company": "space inc.",
    "country": "oceanis"
  },
  "invoice_text": "pay now",
  "tax_name": "VAT",
  "tax_id_name": "VAT ID",
  "tax_id": "100-535-87D",
  "invoice_number": 100,
  "formatted_invoice_number": "2016-X-100",
  "customer_number": 101,
  "items": [
    {
      "id": "53d3fc2107436",
      "paid": false,
      "amount": "1.0",
      "description": "cup of coffee",
      "quantity": "200.0",
      "tax_rate": "20.0",
      "tax_amount": "0.2",
      "amount_with_tax": "1.2",
      "total_amount": "200.0",
      "total_amount_with_tax": "240.0",
      "total_tax_amount": "40.0",
      "accounting_code": "Coffee",
      "cost_center": null,
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    }
  ],
  "total_amount": "240.0",
  "total_amount_without_taxes": "200.0",
  "payable_amount": "240.0",
  "total_paid_amount": "0.0",
  "taxes": [{ "name": "VAT", "rate": "20.0", "amount": "40.0" }],
  "url": "http://some-space.cobot.me/api/invoices/100",
  "paid": false,
  "sent": false,
  "sent_status": "unsent",
  "paid_status": "unpaid",
  "can_charge": true
}

POST https://:subdomain.cobot.me/api/invoices/:id/write_off

Updates an invoice's paid_status to written_off

Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices
POST https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba/write_off

Returns status 201 and the invoice.

DELETE https://:subdomain.cobot.me/api/invoices/:id/write_off

Updates an invoice's paid_status to unpaid.

Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices
DELETE https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba/write_off

Returns status 200 and the invoice.

POST https://:subdomain.cobot.me/api/invoices/:id/charges

Charges a member the invoice's amount using their payment method.

Authentication required:
yes, additionally user must be a space admin or member (members can only charge for their own invoices)
Scope required:
write_invoices
POST https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba/charges

Returns status 200 and the invoice. This call always returns 200 as depending on the payment method the status of the payment is only known after some time.

To get payment errors (for those payment methods that support it), pass return_payment_errors=true as query param. If there's a payment error, the endpoint will return status 422 and {"errors": ["the error message"]}.

DELETE https://:subdomain.cobot.me/api/invoices/:id/charge

When an invoice is scheduled to be charged at a later date, signified by the charge_at attribute, this endpoint cancels that charge.

Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices
DELETE https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba/charge

Returns status 200 and the invoice. charge_at will be set to null.

POST https://:subdomain.cobot.me/api/invoices/:id/notifications

Sends an invoice by email.

Authentication required:
yes, additionally user must be a space admin or member (members can only send their own invoices)
Scope required:
write_invoices
POST https://co-up.cobot.me/api/invoices/cc7e75473a6911587b63d78f4e3f8eba/notifications

Returns status 204 and an empty body.

POST https://:subdomain.cobot.me/api/invoices/:id/items
Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices

Body:

{
  "amount": "10",
  "description": "coffee",
  "tax_rate": "10",
  "quantity": 2,
  "paid": true,
  "accounting_code": "Coffee"
}

Only amount and description are required. Only supply a tax rate if it's different from the invoice's tax rate. Default quantity is 1. If you set paid to true the item will be added to the invoice but will not count towards its payable amount. This is for invoicing people for items they have already paid.

Response:

{
  "id": "675324079fa0875a",
  "amount": "10.0",
  "description": "coffee",
  "tax_rate": "10.0",
  "tax_amount": "1.0",
  "quantity": "2.0",
  "total_amount": "20.0",
  "total_amount_with_tax": "22.0",
  "total_tax_amount": "2.0",
  "paid": true,
  "accounting_code": "Coffee",
  "cost_center": null
}

DELETE https://:subdomain.cobot.me/api/invoices/:id/items/:item_id
Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices

Returns an empty response and status 204. Note that you can't remove the last item from an invoice.

PUT https://:subdomain.cobot.me/api/invoices/:id/items/:item_id
Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices

Body:

{
  "id": "675324079fa0875a",
  "amount": "10.0",
  "description": "coffee",
  "tax_rate": "10.0",
  "tax_amount": "1.0",
  "quantity": "2.0",
  "total_amount": "20.0",
  "total_amount_with_tax": "22.0",
  "total_tax_amount": "2.0",
  "paid": true,
  "accounting_code": "Coffee",
  "cost_center": null
}

Responds with status 200 and the item on success, 422 and errors if you provide invalid data.

PUT https://:subdomain.cobot.me/api/invoices/:id
Authentication required:
yes, additionally user must be a space admin
Scope required:
write_invoices

Example body:

{
  "currency": "EUR",
  "address": {
    "name": "joe doe",
    "full_address": "broadway\n12345 Berlin",
    "company": "joe inc.",
    "country": "ocean"
  },
  "invoice_text": "pay now",
  "tax_id": "100-535-87D",
  "formatted_invoice_number": "2016-X-100",
  "customer_number": 101,
  "items": [
    {
      "id": "53d3fc2107436",
      "paid": false,
      "amount": "80.0",
      "description": "monthly rent",
      "quantity": "2.0",
      "tax_rate": "20.0",
      "tax_amount": "16.0",
      "amount_with_tax": "96.0",
      "total_amount": "160.0",
      "total_amount_with_tax": "192.0",
      "total_tax_amount": "32.0",
      "accounting_code": "FlexPlan",
      "cost_center": null,
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    },
    {
      "id": "53d3fc2107437",
      "paid": false,
      "amount": "20.0",
      "description": "2 time passes",
      "quantity": "2.0",
      "tax_rate": "20.0",
      "tax_amount": "4.0",
      "amount_with_tax": "24.0",
      "total_amount": "40.0",
      "total_amount_with_tax": "48.0",
      "total_tax_amount": "8.0",
      "accounting_code": "Pass",
      "cost_center": null,
      "membership_id": "a9f6bcbed420c37539fa1257e66fd66b"
    }
  ]
}

Responds with status 200 and the updated invoice details on success, 422 and errors if you provide invalid data.

GET https://:subdomain.cobot.me/api/membership/invoice_preview
Authentication required:
yes, additionally user must be member of a space (members can only see their own preview)
Scope required:
read_invoice_preview
GET https://:subdomain.cobot.me/api/memberships/:membership_id/invoice_preview
Authentication required:
yes, additionally user must be admin of the space
Scope required:
read_invoice_preview

Example:

GET http://co-up.cobot.me/api/memberships/17d742f1e365ff351eaca37333586ac8/invoice_preview

GET https://:subdomain.cobot.me/api/teams/:team_id/invoice_preview
Authentication required:
yes, additionally user must be admin of the space
Scope required:
read_invoice_preview

Example:

GET http://co-up.cobot.me/api/teams/17d742f1e365ff351eaca37333586ac8/invoice_preview

DELETE https://:subdomain.cobot.me/api/invoices/:id
Authentication required:
yes, additionally user must be admin of the space
Scope required:
write_invoices, read_invoices

Example:

DELETE http://co-up.cobot.me/api/invoices/3a7195d9cbba0665c16a8437541e69ac

Responds with 204.

GET https://:subdomain.cobot.me/api/invoices/search
Authentication required:
yes, additionally user must be a space admin
Scope required:
read_invoices

Required parameters:

  • query: text query, supports multi word search
GET https://co-up.cobot.me/api/invoices/search?query=Jane%20Doe

Text query searches through: invoice number, invoice items and recipient name or company. Returns paginated list of invoices and number of pages in total.

Example Response:

{
  "total_pages": 2,
  "invoices": [
    array of invoices here (same structure as in "List invoices")
  ]
}

Optional pagination parameters:

  • page: number of page (default: 1)
  • per_page: number of results per page (default: 50)
GET https://co-up.cobot.me/api/invoices/search?query=Jane&page=3&per_page=20

Optional parameters:

  • paid_status: paid, unpaid, written_off, late (accepts comma separated list, default: all)
  • sent_status: sent, unsent (accepts comma separated list, default: all)
  • sort_by: created_at, formatted_invoice_number, paid_status, sent_status, company, name, total_amount (one from the list, default: created_at)
  • sort_direction: asc, desc (one from the list, default: desc)
GET https://co-up.cobot.me/api/invoices/search?query=flexdesk&paid_status=paid%2Cunpaid&sent_status=sent&sort_by=total_amount&sort_direction=asc

Above will return invoices that contain searched expression flexdesk and are either paid or unpaid and are sent, sorted in ascending manner by total amount of the invoice.

If there are no results, it will return an empty list of invoices and total_pages count 0.

GET https://co-up.cobot.me/api/invoices/search?query=flexdesk&paid_status=late

This will return invoices that contain searched expression and are late (unpaid with remind_at date in the past).

back to index