Remote Billing Documents API
The Billing Documents API from Remote — 4 operation(s) for billing documents.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Billing Documents API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Billing Documents
paths:
/v1/billing-documents/{billing_document_id}:
get:
callbacks: {}
deprecated: false
description: 'Shows a billing document details.
Please contact api-support@remote.com to request access to this endpoint.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
'
operationId: get_v1_billing-documents_billing_document_id
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: The billing document's ID
example: 93t3j-billing-doc-id-9suej43
in: path
name: billing_document_id
required: true
schema:
type: string
- description: When true, includes billing document items whose type is not part of the standard set for the invoice type.
example: true
in: query
name: include_unrecognized_types
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillingDocumentResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
summary: Show Billing Document
tags:
- Billing Documents
/v1/billing-documents:
get:
callbacks: {}
deprecated: false
description: 'List billing documents for a company
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
'
operationId: get_v1_billing-documents
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: The month for the billing documents (in ISO-8601 format)
example: '"2023-01"'
in: query
name: period
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillingDocumentsResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
summary: List Billing Documents
tags:
- Billing Documents
/v1/billing-documents/{billing_document_id}/breakdown:
get:
callbacks: {}
deprecated: false
description: 'Get billing document breakdown
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
'
operationId: get_v1_billing-documents_billing_document_id_breakdown
parameters:
- description: The billing document's ID
example: 93t3j-billing-doc-id-9suej43
in: path
name: billing_document_id
required: true
schema:
type: string
- description: Filters the results by the type of the billing breakdown item.
example: base_salary
in: query
name: type
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BillingDocumentBreakdownResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
summary: Get Billing Document Breakdown
tags:
- Billing Documents
/v1/billing-documents/{billing_document_id}/pdf:
get:
callbacks: {}
deprecated: false
description: 'Downloads a billing document PDF
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage invoices (`invoices`) | View invoices (`invoices:read`) | Manage invoices (`invoices:write`) |
'
operationId: get_v1_billing-documents_billing_document_id_pdf
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
- description: The billing document's ID
example: 93t3j-billing-doc-id-9suej43
in: path
name: billing_document_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GenericFile'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- invoices:read
- invoices:write
- invoices
- all:write
- all:read
summary: Download a billing document PDF
tags:
- Billing Documents
components:
schemas:
BillingDocument:
additionalProperties: false
description: A billing document (invoice or credit note) issued to a company by Remote for employment management services.
example:
billing_document_currency: USD
billing_document_number: '12345678901'
billing_document_period: 2023-12
billing_document_type: reconciliation_invoice
company_id: 305ae616-2ef6-4b2d-bed3-b75eb3ccc069
id: 8772a9f1-b43c-46be-a1ce-e50b6819f5ee
issued_date: '2024-03-01'
items:
- billing_document_amount: 1000000
billing_document_currency: USD
employment_id: 0d25c513-employment-id-198557128104
source_amount: 500000
source_currency: USD
type: base_salary
total: '12345'
properties:
billing_document_currency:
description: The ISO 4217 currency code of the billing document.
type: string
billing_document_number:
description: The human-readable document number (e.g., invoice number).
type: string
billing_document_period:
description: The billing period this document covers, in YYYY-MM format.
type: string
billing_document_type:
description: 'The type of billing document.
- `reconciliation_invoice`: A regular invoice reconciling payroll costs for the period.
- `prefunding_invoice`: An invoice for advance funding of payroll before it is processed.
- `supplemental_service_invoice`: An invoice for additional services beyond standard payroll.
- `reconciliation_credit_note`: A credit note adjusting a previous reconciliation invoice.
'
type: string
company_id:
description: The unique identifier (UUID) of the company this billing document belongs to.
type: string
id:
description: The unique identifier (UUID) of the billing document.
type: string
issued_date:
description: The date the billing document was issued (ISO 8601 date format).
type: string
items:
description: The line items that make up this billing document.
items:
$ref: '#/components/schemas/BillingDocumentAmountItem'
type: array
total:
description: The total amount of the billing document, in cents.
type: integer
required:
- id
- billing_document_period
- billing_document_number
- billing_document_type
- company_id
- issued_date
- billing_document_currency
- total
- items
title: BillingDocument
type: object
ParameterError:
example:
code: invalid_param
message: Invalid parameter
param: employment_id
properties:
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
param:
description: The parameter that lead to the error message.
type: string
required:
- code
- message
- param
title: ParameterError
type: object
BillingDocumentAmountItem:
additionalProperties: false
description: A line item on a billing document, representing a specific cost category (e.g., base salary, allowances, taxes) for an employment.
example:
billing_document_amount: 1000000
billing_document_currency: USD
employment_id: 0d25c513-employment-id-198557128104
source_amount: 500000
source_currency: USD
type: base_salary
properties:
billing_document_amount:
description: The amount for this line item in the billing document currency, in cents.
type: integer
billing_document_currency:
description: The ISO 4217 currency code of the billing document.
nullable: true
type: string
employment_id:
description: The unique identifier (UUID) of the employment this line item relates to. Null for company-level charges.
nullable: true
type: string
source_amount:
description: The original amount in the source (local) currency, in cents. May differ from billing_document_amount due to currency conversion.
type: integer
source_currency:
description: The ISO 4217 currency code of the source (local) currency. Null if same as billing document currency.
nullable: true
type: string
type:
description: The cost category for this line item (e.g., "base_salary", "allowances", "bonuses", "deductions", "taxes").
type: string
required:
- type
- billing_document_amount
- billing_document_currency
title: BillingDocumentAmountItem
type: object
UnauthorizedResponse:
description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
example:
message: Unauthorized
properties:
message:
pattern: Unauthorized
type: string
required:
- message
title: UnauthorizedResponse
type: object
BillingDocumentBreakdownResponse:
additionalProperties: false
description: Information about a billing document breakdown
example:
data:
billing_document_breakdown:
- country_code: PRT
description: Base Salary
employment_id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
fx_rate: '0.9'
invoice_amount: 900000
invoice_currency: EUR
invoice_number: '1234567890'
invoice_period: 2023-12
source_amount: 1000000
source_currency: USD
type: Base Salary
variance_from_invoice: May vary from invoice by under USD 1.00 (or equivalent)
variance_from_invoice_amount: 0
properties:
data:
properties:
billing_document_breakdown:
items:
$ref: '#/components/schemas/BillingDocumentBreakdownItem'
type: array
required:
- billing_document_breakdown
type: object
required:
- data
title: BillingDocumentBreakdownResponse
type: object
BillingDocumentsResponse:
additionalProperties: false
description: Information about a list of billing documents
example:
data:
billing_documents:
- billing_document_period: 2023-12
billing_document_type: reconciliation_invoice
id: 8772a9f1-b43c-46be-a1ce-e50b6819f5ee
current_page: 1
total_count: 1
total_pages: 1
properties:
data:
properties:
billing_documents:
items:
properties:
bill_from:
description: The entity issuing the billing document. Null if not applicable.
nullable: true
type: string
billing_document_period:
description: The billing period in YYYY-MM format.
type: string
billing_document_type:
enum:
- reconciliation_invoice
- prefunding_invoice
- supplemental_service_invoice
- reconciliation_credit_note
type: string
id:
description: The unique identifier (UUID) of the billing document.
type: string
type: array
current_page:
description: The current page among all of the total_pages
example: 1
type: integer
total_count:
description: The total number of records returned counting all pages
example: 100
type: integer
total_pages:
description: The total number of pages the user can go through
example: 10
type: integer
required:
- billing_documents
- current_page
- total_pages
- total_count
type: object
required:
- data
title: BillingDocumentsResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
BillingDocumentResponse:
additionalProperties: false
description: Information of a billing document
example:
data:
billing_document:
billing_document_currency: USD
billing_document_number: '12345678901'
billing_document_period: 2023-12
billing_document_type: reconciliation_invoice
company_id: 305ae616-2ef6-4b2d-bed3-b75eb3ccc069
id: 8772a9f1-b43c-46be-a1ce-e50b6819f5ee
issued_date: '2024-03-01'
items:
- billing_document_amount: 1000000
billing_document_currency: USD
employment_id: 0d25c513-employment-id-198557128104
source_amount: 500000
source_currency: USD
type: base_salary
total: '12345'
properties:
data:
properties:
billing_document:
$ref: '#/components/schemas/BillingDocument'
required:
- billing_document
type: object
required:
- data
title: BillingDocumentResponse
type: object
UnprocessableEntityResponse:
anyOf:
- properties:
errors:
type: object
required:
- errors
type: object
- properties:
message:
oneOf:
- type: string
- $ref: '#/components/schemas/ParameterError'
- items:
$ref: '#/components/schemas/ParameterError'
title: ParameterErrors
type: array
- $ref: '#/components/schemas/ActionError'
- items:
$ref: '#/components/schemas/ActionError'
title: ActionErrors
type: array
required:
- message
type: object
example:
errors:
some_field:
- is invalid
title: UnprocessableEntityResponse
type: object
BadRequestResponse:
description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
example:
message: invalid {resource}
oneOf:
- properties:
message:
description: A human-readable error message describing what was wrong with the request.
type: string
required:
- message
type: object
- properties:
message:
properties:
code:
type: string
message:
type: string
required:
- code
- message
type: object
type: object
title: BadRequestResponse
type: object
GenericFile:
description: A file represented as a base64-encoded string.
example: base64 encoded content
format: binary
title: GenericFile
type: string
BillingDocumentBreakdownItem:
additionalProperties: false
description: Item in a billing document breakdown
example:
country_code: PRT
description: Base Salary
employment_id: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
fx_rate: '0.9'
invoice_amount: 900000
invoice_currency: EUR
invoice_number: '1234567890'
invoice_period: 2023-12
source_amount: 1000000
source_currency: USD
type: Base Salary
variance_from_invoice: May vary from invoice by under USD 1.00 (or equivalent)
variance_from_invoice_amount: 0
properties:
country_code:
$ref: '#/components/schemas/CountryCode'
description:
description: A human-readable description of this cost item.
type: string
employment_id:
$ref: '#/components/schemas/UuidSlug'
fx_rate:
description: The foreign exchange rate applied to convert from the source currency to the invoice currency.
type: string
invoice_amount:
description: Invoice amount in cents
type: integer
invoice_currency:
$ref: '#/components/schemas/CurrencyCode'
invoice_number:
description: The invoice number associated with this breakdown item.
type: string
invoice_period:
description: The invoice period in YYYY-MM format.
type: string
source_amount:
description: Source amount in cents
type: integer
source_currency:
$ref: '#/components/schemas/CurrencyCode'
type:
description: The cost category (e.g., "Base Salary", "Employer Contributions", "Benefits").
type: string
variance_from_invoice:
description: A human-readable note about any variance between the breakdown amount and the invoiced amount, typically due to FX rounding.
nullable: true
type: string
variance_from_invoice_amount:
description: Variance from invoice amount in cents
nullable: true
type: integer
required:
- employment_id
- invoice_number
- invoice_period
- country_code
- type
- description
- invoice_amount
- invoice_currency
- source_amount
- source_currency
- variance_from_invoice
- variance_from_invoice_amount
- fx_rate
title: BillingDocumentBreakdownItem
type: object
CurrencyCode:
description: Currency code of the SWIFT fee. Only present when processing_fee is set.
example: BRL
maxLength: 3
minLength: 3
nullable: true
title: CurrencyCode
type: string
CountryCode:
description: Country code according to ISO 3166-1 3-digit alphabetic codes.
example: PRT
title: CountryCode
type: string
UuidSlug:
description: Identifier of the employment being terminated.
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
format: uuid
title: UuidSlug
type: string
TooManyRequestsResponse:
description: Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.
example:
message: Too many requests
properties:
message:
pattern: Too many requests
type: string
title: TooManyRequestsResponse
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
code:
description: An error code that describes the nature of the error.
type: string
message:
description: A developer friendly error message that gives details on what the error was and how it may be remedied.
type: string
required:
- code
- message
- action
title: ActionError
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer`
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-billing-documents-api-openapi.yml