---
title: "Create Contractor Invoice Schedules"
method: POST
path: "/v1/contractor-invoice-schedules"
tags: ["Invoice Schedules"]
---

# Create Contractor Invoice Schedules

`POST /v1/contractor-invoice-schedules`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/contractor-invoice-schedules`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `invoices:write`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `invoices:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Creates many invoice schedules records.
It's supposed to return two lists: one containing created records, and another one containing the schedules that failed to be inserted.

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:write` works too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage invoices (`invoices`) | - | Manage invoices (`invoices:write`) |
| Company-scoped access token (assertion) | Manage invoices (`invoices`) | - | Manage invoices (`invoices:write`) |
| Customer API token | Manage invoices (`invoices`) | - | Manage invoices (`invoices:write`) |

## Request body

- BulkContractorInvoiceScheduleCreateParams: Schema defining a bulk creation payload.
  - `contractor_invoice_schedules` ContractorInvoiceScheduleCreateParams[], required: List of invoice schedules payload.
    - `currency` string, nullable, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    - `custom_days` integer[], nullable: The two calendar days of the month on which invoices are generated. Only applies when `periodicity` is `semi_monthly`; must be omitted (or `null`) for every other periodicity. When omitted for a `semi_monthly` schedule, the two days are derived from `start_date`: the start day and the day 14 days apart from it. Supply this field only to pick a cycle other than that default. One of the two days must be the day of `start_date`, the days must be distinct, and they cannot resolve to the same day within a month.
    - `employment_id` string, uuid, required: Employment identifier
    - `items` ContractorInvoiceScheduleItem[], required: List of invoice items that composes the overall invoice amount.
      - `amount` integer, required: Amount, in cents.
      - `description` string, required: Describes invoice item intent.
    - `note` string: Custom defined note.
    - `nr_occurrences` integer: Count of invoices that should be generated during schedule lifetime. Omit for a schedule that repeats indefinitely. A one-off invoice is expressed as `nr_occurrences: 1` — there is no `one_time` periodicity. Pair it with any `periodicity` (`monthly` is conventional); the schedule completes after its single invoice, so the cadence never applies.
    - `number` string: Invoice identifier.
    - `periodicity` 'bi_weekly' | 'monthly' | 'semi_monthly' | 'weekly', required: Defines how often contractor invoices will be generated. - `bi_weekly`: Invoices will be generated every other week, on the given day of the week based on the start date. - `monthly`: Invoices will be generated once a month. - `semi_monthly`: Invoices will be generated at fixed dates twice a month (with 14 days of difference between each other), depending on the start date. In months with just 30 days, if `start_date` is set to the 31st day, then generation occurs in the last of day of the month. - `weekly`: Invoices will be generated each week.
    - `start_date` string, date, required: Date of the first contractor invoice generation.

## Response `201`

All entries have been created

- BulkContractorInvoiceScheduleCreateResponse: Response containing the lists of succeeded and failed schedules.
  - `data` object, required
    - `failures` ContractorInvoiceScheduleCreateResponseFailure[], required
      - `currency` string, nullable, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
      - `custom_days` integer[], nullable: The two calendar days of the month on which invoices are generated. Only applies when `periodicity` is `semi_monthly`; must be omitted (or `null`) for every other periodicity. When omitted for a `semi_monthly` schedule, the two days are derived from `start_date`: the start day and the day 14 days apart from it. Supply this field only to pick a cycle other than that default. One of the two days must be the day of `start_date`, the days must be distinct, and they cannot resolve to the same day within a month.
      - `employment_id` string, uuid, required: Employment identifier
      - `errors` object, required
        - `currency` string[]
        - `custom_days` string[]
        - `employment_id` string[]
        - `items` object[]
          - `amount` string[]
          - `description` string[]
        - `note` string[]
        - `nr_occurrences` string[]
        - `number` string[]
        - `periodicity` string[]
        - `start_date` string[]
      - `items` ContractorInvoiceScheduleItem[], required: List of invoice items that composes the overall invoice amount.
        - `amount` integer, required: Amount, in cents.
        - `description` string, required: Describes invoice item intent.
      - `note` string: Custom defined note.
      - `nr_occurrences` integer: Count of invoices that should be generated during schedule lifetime. Omit for a schedule that repeats indefinitely. A one-off invoice is expressed as `nr_occurrences: 1` — there is no `one_time` periodicity. Pair it with any `periodicity` (`monthly` is conventional); the schedule completes after its single invoice, so the cadence never applies.
      - `number` string: Invoice identifier.
      - `periodicity` 'bi_weekly' | 'monthly' | 'semi_monthly' | 'weekly', required: Defines how often contractor invoices will be generated. - `bi_weekly`: Invoices will be generated every other week, on the given day of the week based on the start date. - `monthly`: Invoices will be generated once a month. - `semi_monthly`: Invoices will be generated at fixed dates twice a month (with 14 days of difference between each other), depending on the start date. In months with just 30 days, if `start_date` is set to the 31st day, then generation occurs in the last of day of the month. - `weekly`: Invoices will be generated each week.
      - `start_date` string, date, required: Date of the first contractor invoice generation.
    - `successes` ContractorInvoiceScheduleCreateResponseSuccess[], required
      - `currency` string, nullable, required: Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
      - `custom_days` integer[], nullable: The two calendar days of the month on which invoices are generated. Only applies when `periodicity` is `semi_monthly`; must be omitted (or `null`) for every other periodicity. When omitted for a `semi_monthly` schedule, the two days are derived from `start_date`: the start day and the day 14 days apart from it. Supply this field only to pick a cycle other than that default. One of the two days must be the day of `start_date`, the days must be distinct, and they cannot resolve to the same day within a month.
      - `employment_id` string, uuid, required: Employment identifier
      - `id` string, uuid, required: A unique identifier in UUID v4 format.
      - `items` ContractorInvoiceScheduleItem[], required: List of invoice items that composes the overall invoice amount.
        - `amount` integer, required: Amount, in cents.
        - `description` string, required: Describes invoice item intent.
      - `note` string: Custom defined note.
      - `nr_occurrences` integer: Count of invoices that should be generated during schedule lifetime. Omit for a schedule that repeats indefinitely. A one-off invoice is expressed as `nr_occurrences: 1` — there is no `one_time` periodicity. Pair it with any `periodicity` (`monthly` is conventional); the schedule completes after its single invoice, so the cadence never applies.
      - `number` string: Invoice identifier.
      - `periodicity` 'bi_weekly' | 'monthly' | 'semi_monthly' | 'weekly', required: Defines how often contractor invoices will be generated. - `bi_weekly`: Invoices will be generated every other week, on the given day of the week based on the start date. - `monthly`: Invoices will be generated once a month. - `semi_monthly`: Invoices will be generated at fixed dates twice a month (with 14 days of difference between each other), depending on the start date. In months with just 30 days, if `start_date` is set to the 31st day, then generation occurs in the last of day of the month. - `weekly`: Invoices will be generated each week.
      - `start_date` string, date, required: Date of the first contractor invoice generation.

## Other responses

- `207`: Multiple successes and failures
- `403`: Forbidden
- `404`: Not Found
- `422`: All entries had failed

---

[API](https://skmtc.dev/remote-com/apis/contractors.md) - [All operations](https://skmtc.dev/remote-com/apis/contractors/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/contractors/revisions/e1e7f1caaada?raw)