Working with Expenses
Overview
In this guide, you will learn:
- Possible operations that can be performed on an expense
- Meaning of the response fields
Before you get started
The Remote API has the capability to create already approved expenses, to update pending expenses to approve or decline them, and to show and list expenses. Each expense belongs to an employment, has an amount in a given currency, the date it was incurred, and a receipt file.
Before you get started, you’ll need to ensure that you know the employment_id
.
Creating an Expense
When creating an expense in a different currency of the employment, for instance, a €100.00 expense that belongs to an American employment, it is possible to send the following request:
curl --location --request POST 'https://gateway.remote-sandbox.com/v1/expenses' \
--header 'Authorization: Bearer <your token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"employment_id": "7db936d5-ea9b-4e97-a1f3-4d94ca39c294",
"amount": 10000,
"category": "education_training",
"currency": "EUR",
"expense_date": "2023-01-10",
"receipt": {
"content": "UGVyaW9kI...DAsMCwwLDEwMCwwCg==",
"name": "receipt.pdf"
},
"tax_amount": 0,
"timezone": "Etc/UTC",
"title": "Giving Constructive Feedback Training",
"reviewed_at": "2023-02-10T00:00:00Z"
}'
Receipt
The receipt
field represents the receipt of the purchase, which is required to create an expense. The file name and the content encoded in base64 define a receipt to be attached to the expense. The receipt is necessary to create an expense.
To get the base64-encoded file content via the command line, you can run:
$ base64 -i path/to/file.pdf
JVBERi0xLjQKJcOkw7zDtsP922jjaA+hXY1Wh1aNVo...Kc3RhcnR4cmVmCjEyNzg3CiUlRU9GCg==
The response will look like this:
{
"data": {
"expense": {
"amount": 10000,
"category": "education_training",
"converted_amount": 10735,
"converted_currency": {
"code": "USD",
"name": "United States Dollar",
"symbol": "$"
},
"converted_tax_amount": 0,
"currency": {
"code": "EUR",
"name": "European Euro",
"symbol": "€"
},
"employment_id": "7db936d5-ea9b-4e97-a1f3-4d94ca39c294",
"expense_date": "2023-01-10",
"id": "c26257a7-1cb5-4cd1-bf76-3ed0a389979c",
"invoice_period": null,
"notes": null,
"reason": null,
"reviewed_at": "2023-02-10",
"reviewer": {
"user_email": "[email protected]",
"user_id": "2f73619f-4970-4c23-a7bb-3d110a7e6cf2",
"user_name": "Jane Smith"
},
"status": "approved",
"tax_amount": 0,
"title": "Giving Constructive Feedback Training 5"
}
}
}
In this example, we created an expense with the source currency in EUR
but the amount was converted to USD
, since it is an American worker. If the expense is in the same currency as the country the employment was created, the amount will be the same.
Response Fields
As shown, the response object contains some fields that weren't explicitly required in the creation. Next, they're presented in more detail.
Currencies
To create an expense, the request parameters must have the cost in the currency that the expense was paid. That can also be referred to as the source currency.
The response object for the create, show, and list expenses requests, returns the amount and currency of the expense in both source currency (amount
and currency
fields) and in the converted currency (converted_amount
and converted_currency
fields), which is the currency the employee or contractor will be paid in. The same definitions apply to the tax fields (tax_amount
and converted_tax_amount
).
Revision
The reviewer_id
and reviewed_at
fields are optional when creating an expense. If the approver of the expense is a user in Remote, it is possible to provide the user_id
for the reviewer_id
field. If the value is not provided, it will default to the user that generated the API access token. The same applies to the reviewed_at
field. If the timestamp is not provided, it will be set to the timestamp of when the request was done.
To search for possible user_id
s to set the reviewers, query the /company-managers
endpoint.
You can check the documentation for it here.
Approving or Declining an Expense
You can approve or decline a pending expense using the PUT /expenses/:id
or PATCH /expenses/:id
endpoints. The :id
in the query parameter must be replaced with the ID of the expense to be updated.
To approve an expense, simply update its status to approved
. Conversely, to decline an expense, update its status to declined
and provide a reason for declination:
{
"status": "declined",
"reason": "Expense not refundable"
}
Fetching the receipt file
As mentioned, a receipt is a required parameter to create an expense. To retrieve the file sent when creating the expense, send a request to the GET /expenses/:id/receipt
endpoint. The :id
in the query parameter must be a valid expense ID, which you can obtain from the List Expenses endpoint, for example. Here's an example of how to fetch the receipt file:
$ curl --location --request POST 'https://gateway.remote-sandbox.com/v1/expenses/c26257a7-1cb5-4cd1-bf76-3ed0a389979c/receipt' \
--header 'Authorization: Bearer <your token>' \
--header 'Content-Type: application/json'
$ // receipt.pdf binary file content
Getting notified on events
You can receive notifications for changes in expenses by subscribing to the following events:
expense.submitted
, triggered when an approved expense is submitted to Remote;expense.updated
, triggered for any modification of an expense, except when it is deleted;expense.deleted
, triggered when an expense is deleted by an employee.
It is important to note that when an employee modifies a declined expense, it will be moved back to the pending
status and then both expense.submitted
and expense.updated
events will be triggered.
Please refer to the API Reference documentation to obtain the most up-to-date information about the data sent and available events. Additionally, check the Working with Webhooks Guide to learn how to register and test webhooks.
Other operations
There's also the GET /expenses
endpoint, to query the list of expenses of all employments that belong to the company, and the GET /expenses/:id
endpoint, to show information of a single expense. Some other operations involving expense reimbursement request that has not been approved, are not yet supported. However, please contact Remote at [email protected]
if you need a feature that is not available.
Updated 4 months ago