Purchases
German: “Ausgaben”
- Attributes
- GET /purchases
- GET /purchases/{id}
- POST /purchases
- POST /purchases/{id}/assign_to_project
- PATCH /purchases/{id}/update_status
- PATCH /purchases/{id}/store_document
- DELETE /purchases/{id}
Attributes
Includes among the standard fields for purchases also:
- tags
- company (if the purchase is associated to a supplier)
- payments (list of payments made for the purchase)
- user
- status (“pending” = Inbox, “approved” = Archive)
- items
- items.vat (“tax”, “reverse_charge”, “intra_eu” (intra community trade, only applicable for accounts in the EU))
- items.expense (the associated project expense or
null
) - items.receipt (the associated receipt or
null
)
{
"id": 987,
"identifier": "E2016-0001",
"receipt_identifier": "KK121",
"title": "SBB Ticket",
"info": null,
"iban": "CH3908704016075473007",
"reference": null,
"date": "2020-02-28",
"due_date": null,
"service_period_from": "2020-02-28",
"service_period_to": "2020-02-28",
"status": "pending",
"payment_method": "bank_transfer",
"net_total": 44.88,
"gross_total": 46.0,
"currency": "CHF",
"file_url": null,
"custom_properties": { "Various": "some stuff" },
"tags": ["Transportation"],
"company": {
"id": 5552,
"name": "Schweizerische Bundesbahnen SBB",
"iban": "CH3908704016075473007"
},
"payments": [],
"user": {
"id": 433109936,
"firstname": "Mario",
"name": "Rossi"
},
"refund_request": {
"id": 66129936,
"comment": "My receipts",
"user_id": 123456
},
"items": [
{
"id": 311936153,
"title": "SBB Ticket",
"net_total": 44.88,
"tax_total": 1.12,
"tax": 2.5,
"vat": { "tax": 2.5, "reverse_charge": false, "intra_eu": false, "active": true },
"tax_included": true,
"gross_total": 46.0,
"category": {
"id": 671034328,
"name": "Spesen und Reisekosten",
"credit_account": "6640"
},
"supplier_credit_number": 70001,
"expense": {
"id": 7655423,
"project": {
"id": 23345545,
"company_id": 54345
}
},
"receipt": {
"id": 9857765,
"title": "SBB Ticket",
"date": "2018-10-01",
"attachment_url": "https://..."
}
}
],
"created_at": "2018-10-17T09:33:46Z",
"updated_at": "2018-10-17T09:33:46Z"
}
GET /purchases
Retrieve all purchases:
curl -X GET \
'https://{domain}.mocoapp.com/api/v1/purchases' \
-H 'Authorization: Token token=YOUR_API_KEY'
It’s also possible to filter:
- Global filters apply
- category_id – identifier of the purchases’ category,
- term – full text search on purchase positions,
- company_id – identifier of the supplier, pass 0 to get the purchases not associated to a supplier,
- status – “pending” or “approved” (Inbox / Archive)
- not_booked – true/false
- tags – “Transportation, Restaurants” (comma separated list)
- date – date range in the form 2020-02-01:2020-02-22
- unpaid – filter only purchases without a payment
- payment_method – possible values are: “bank_transfer”, “direct_debit”, “credit_card”, “paypal” or “cash”
- receipt_identifier – filter by the receipts invoice number, e.g. R2023-1234. It must be unique scoped by supplier.
- identifier – filter by purchase identifier, e.g. E2312-0001
Returns an array with all purchases information (see attributes).
GET /purchases/{id}
Retrieve a single purchase:
curl -X GET \
'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \
-H 'Authorization: Token token=YOUR_API_KEY'
Returns the representation for a single purchase.
POST /purchases
Create a purchase:
curl -X POST \
'https://{domain}.mocoapp.com/api/v1/purchases' \
-H 'Authorization: Token token=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '
{
"date": "2020-02-02",
"currency": "EUR",
"payment_method": "bank_transfer",
"receipt_identifier": "XXLA",
"custom_properties": { "Various": "Stuff" },
"items": [
{
"title": "Ticket",
"total": 30,
"tax": 10,
"tax_included": true
}
],
"file": {
"filename": "document.pdf",
"base64": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx..."
}
}'
Mandatory fields are marked with a star (*):
- date* – “2020-02-02”
- currency* – “CHF” (a valid currency of the account)
- payment_method* – “bank_transfer”, “direct_debit”, “credit_card”, “paypal”, “cash”
- title – set the title for this purchase. If left out, the title is generated from the positions.
- items* – list of position. At least one position must be present and every position has the following fields:
- title* – Ticket
- total* – 30
- tax* – 7.7 (tax percentage)
- tax_included – true (specify if the total includes the tax or not)
- category_id – 123 (reference to a purchase category)
- due_date – “2020-02-18”
- service_period_from – “2020-01-01”
- service_period_to – “2020-01-31”
- status - “pending” or “approved”
- due_date – “2020-02-18”
- company_id – 211 (reference to the supplier)
- user_id – 123 (reference to the responsible user)
- receipt_identifier – 123
- info – free text
- iban – CH123
- reference – ref
- custom_property_values – {“Field”: “Value}
- file – file attached to the purchase, with the following fields:
- filename – “document.pdf”
- base64 – base64 encoded content of the file
- tags – [“Label1”, “Label2”]
POST /purchases/{id}/assign_to_project
Assign a purchase item to a project by creating or linking to an expense in the project. The assignment has to be done per line item explicitly.
curl -X POST \
'https://{domain}.mocoapp.com/api/v1/purchases/{id}/assign_to_project' \
-H 'Authorization: Token token=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '
{
"item_id": 311936153,
"project_id": 23345545,
"expense_id": 7655423,
"notify_project_leader": true,
"billable": true,
"budget_relevant": true,
"surcharge": true
}'
Mandatory fields are marked with a star (*):
- item_id* – 311936153 (reference to the purchase item)
- project_id* – 23345545 (reference to the project)
- expense_id – 7655423 (reference to the project expense, if empty, a new one is created)
- notify_project_leader – true (send a notification to the project if an expense is created)
- surcharge – true/false (if provided in account settings, the surcharge will be applied)
The following fields will override account settings only if provided:
- billable – true (if the expense is billable)
- budget_relevant – true (if the expense is budget relevant)
PATCH /purchases/{id}/update_status
Updates the purchase status:
curl -X PATCH \
'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \
-H 'Authorization: Token token=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '
{
"status": "approved"
}'
- status* – “pending”, “approved”
PATCH /purchases/{id}/store_document
Submits the purchase’s document using multipart/form-data
format if it has to be changed afterwards or was not submitted with the initial creation.
curl -X PATCH \
'https://{domain}.mocoapp.com/api/v1/purchases/{id}/store_document' \
-H 'Authorization: Token token=YOUR_API_KEY' \
-F file=@/path/to/file.pdf
- file* – path to the document to store
DELETE /purchases/{id}
Deletes a purchase. It’s possible only if the status is pending and no payments have been registered.
curl -X DELETE \
'https://{domain}.mocoapp.com/api/v1/purchases/{id}' \
-H 'Authorization: Token token=YOUR_API_KEY'