Codat.Platform.SyncSettings (codat v1.0.0)

Manage data sync schedules for a company's connections.

Sync settings control how frequently Codat pulls each data type from an integration. You can configure sync frequency globally (via the Portal) or per-company using this module.

Supported Frequencies

Value (hours)	Description
`1`	Hourly (paid plans only)
`24`	Daily
`168`	Weekly
`720`	Monthly
`0`	Off — no automatic sync

Note: Hourly sync is only available on paid plans. Attempting to set hourly sync on a free account will return a 402 Payment Required error.

Example

# Get current sync settings for a company
{:ok, settings} = Codat.Platform.SyncSettings.get(client, "company-id")
settings["overridesDefaults"]  # => false
settings["settings"]  # => [%{"dataType" => "invoices", "fetchOnFirstLink" => true, "syncSchedule" => %{"hourOfDay" => 0, "intervalHours" => 24}}, ...]

# Update a company's sync schedule
{:ok, _} = Codat.Platform.SyncSettings.update(client, "company-id", %{
  overridesDefaults: true,
  settings: [
    %{
      dataType: "invoices",
      fetchOnFirstLink: true,
      syncSchedule: %{
        intervalHours: 1,    # Hourly — requires paid plan
        hourOfDay: 0
      }
    },
    %{
      dataType: "bills",
      fetchOnFirstLink: true,
      syncSchedule: %{
        intervalHours: 24,
        hourOfDay: 2
      }
    }
  ]
})

Summary

Functions

get(client_or_company_id, id_or_opts \\ [])

Returns the sync settings for a company.

update(client_or_company_id, company_or_body, body_or_opts \\ [])

Updates the sync settings for a company.

Functions

get(client_or_company_id, id_or_opts \\ [])

@spec get(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Returns the sync settings for a company.

If overridesDefaults is false, the company uses your account's default sync schedule configured in the Codat Portal.

Example

{:ok, settings} = Codat.Platform.SyncSettings.get(client, "company-id")

update(client_or_company_id, company_or_body, body_or_opts \\ [])

@spec update(Codat.Client.t() | String.t(), String.t() | map(), map() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Updates the sync settings for a company.

Pass overridesDefaults: true to use company-specific settings. Pass overridesDefaults: false to revert to the account default schedule.

Payload Shape

%{
  overridesDefaults: true,
  settings: [
    %{
      dataType: "invoices",          # Required — the data type name
      fetchOnFirstLink: true,        # Sync on first connection?
      syncSchedule: %{
        intervalHours: 24,           # 0, 1, 24, 168, or 720
        hourOfDay: 0                 # UTC hour to start sync (0-23)
      }
    }
  ]
}

Example

# Set invoices to hourly sync, bills to daily
{:ok, _} = Codat.Platform.SyncSettings.update(client, "company-id", %{
  overridesDefaults: true,
  settings: [
    %{dataType: "invoices", fetchOnFirstLink: true, syncSchedule: %{intervalHours: 1, hourOfDay: 0}},
    %{dataType: "bills",    fetchOnFirstLink: true, syncSchedule: %{intervalHours: 24, hourOfDay: 3}}
  ]
})