Skip to main content

Orb full reference

This is the full reference documentation for the Orb agent connector.

Supported entities and actions

The Orb connector supports the following entities and actions.

EntityActions
CustomersList, Get, Search
SubscriptionsList, Get, Search
PlansList, Get, Search
InvoicesList, Get, Search

Customers

Customers List

Returns a paginated list of customers

Python SDK

await orb.customers.list()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "customers",
"action": "list"
}'

Parameters

Parameter NameTypeRequiredDescription
limitintegerNoNumber of items to return per page
cursorstringNoCursor for pagination
Response Schema

Records

Field NameTypeDescription
idstring
external_customer_idstring | null
namestring | null
emailstring | null
created_atstring | null
payment_providerstring | null
payment_provider_idstring | null
timezonestring | null
shipping_addressobject | any
billing_addressobject | any
balancestring | null
currencystring | null
tax_idobject | null
auto_collectionboolean | null
metadataobject | null

Meta

Field NameTypeDescription
next_cursorstring | null

Customers Get

Get a single customer by ID

Python SDK

await orb.customers.get(
customer_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "customers",
"action": "get",
"params": {
"customer_id": "<str>"
}
}'

Parameters

Parameter NameTypeRequiredDescription
customer_idstringYesCustomer ID
Response Schema

Records

Field NameTypeDescription
idstring
external_customer_idstring | null
namestring | null
emailstring | null
created_atstring | null
payment_providerstring | null
payment_provider_idstring | null
timezonestring | null
shipping_addressobject | any
billing_addressobject | any
balancestring | null
currencystring | null
tax_idobject | null
auto_collectionboolean | null
metadataobject | null

Search and filter customers records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await orb.customers.search(
query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "customers",
"action": "search",
"params": {
"query": {"filter": {"eq": {"id": "<str>"}}}
}
}'

Parameters

Parameter NameTypeRequiredDescription
queryobjectYesFilter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
query.filterobjectNoFilter conditions
query.sortarrayNoSort conditions
limitintegerNoMaximum results to return (default 1000)
cursorstringNoPagination cursor from previous response's next_cursor
fieldsarrayNoField paths to include in results

Searchable Fields

Field NameTypeDescription
idstringThe unique identifier of the customer
external_customer_idstringThe ID of the customer in an external system
namestringThe name of the customer
emailstringThe email address of the customer
created_atstringThe date and time when the customer was created
payment_providerstringThe payment provider used by the customer
payment_provider_idstringThe ID of the customer in the payment provider's system
timezonestringThe timezone setting of the customer
shipping_addressobjectThe shipping address of the customer
billing_addressobjectThe billing address of the customer
balancestringThe current balance of the customer
currencystringThe currency of the customer
auto_collectionbooleanWhether auto collection is enabled
metadataobjectAdditional metadata for the customer
Response Schema
Field NameTypeDescription
hitsarrayList of matching records
hits[].idstringRecord identifier
hits[].scorenumberRelevance score
hits[].dataobjectRecord data containing the searchable fields listed above
hits[].data.idstringThe unique identifier of the customer
hits[].data.external_customer_idstringThe ID of the customer in an external system
hits[].data.namestringThe name of the customer
hits[].data.emailstringThe email address of the customer
hits[].data.created_atstringThe date and time when the customer was created
hits[].data.payment_providerstringThe payment provider used by the customer
hits[].data.payment_provider_idstringThe ID of the customer in the payment provider's system
hits[].data.timezonestringThe timezone setting of the customer
hits[].data.shipping_addressobjectThe shipping address of the customer
hits[].data.billing_addressobjectThe billing address of the customer
hits[].data.balancestringThe current balance of the customer
hits[].data.currencystringThe currency of the customer
hits[].data.auto_collectionbooleanWhether auto collection is enabled
hits[].data.metadataobjectAdditional metadata for the customer
next_cursorstring | nullCursor for next page of results
took_msnumberQuery execution time in milliseconds

Subscriptions

Subscriptions List

Returns a paginated list of subscriptions

Python SDK

await orb.subscriptions.list()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "subscriptions",
"action": "list"
}'

Parameters

Parameter NameTypeRequiredDescription
limitintegerNoNumber of items to return per page
cursorstringNoCursor for pagination
customer_idstringNoFilter subscriptions by customer ID
external_customer_idstringNoFilter subscriptions by external customer ID
status"active" | "ended" | "upcoming"NoFilter subscriptions by status
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
start_datestring | null
end_datestring | null
statusstring | null
customerobject | null
planobject | null
current_billing_period_start_datestring | null
current_billing_period_end_datestring | null
active_plan_phase_orderinteger | null
fixed_fee_quantity_schedulearray | null
price_intervalsarray | null
redeemed_couponobject | null
default_invoice_memostring | null
auto_collectionboolean | null
net_termsinteger | null
invoicing_thresholdstring | null
metadataobject | null

Meta

Field NameTypeDescription
next_cursorstring | null

Subscriptions Get

Get a single subscription by ID

Python SDK

await orb.subscriptions.get(
subscription_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "subscriptions",
"action": "get",
"params": {
"subscription_id": "<str>"
}
}'

Parameters

Parameter NameTypeRequiredDescription
subscription_idstringYesSubscription ID
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
start_datestring | null
end_datestring | null
statusstring | null
customerobject | null
planobject | null
current_billing_period_start_datestring | null
current_billing_period_end_datestring | null
active_plan_phase_orderinteger | null
fixed_fee_quantity_schedulearray | null
price_intervalsarray | null
redeemed_couponobject | null
default_invoice_memostring | null
auto_collectionboolean | null
net_termsinteger | null
invoicing_thresholdstring | null
metadataobject | null

Search and filter subscriptions records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await orb.subscriptions.search(
query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "subscriptions",
"action": "search",
"params": {
"query": {"filter": {"eq": {"id": "<str>"}}}
}
}'

Parameters

Parameter NameTypeRequiredDescription
queryobjectYesFilter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
query.filterobjectNoFilter conditions
query.sortarrayNoSort conditions
limitintegerNoMaximum results to return (default 1000)
cursorstringNoPagination cursor from previous response's next_cursor
fieldsarrayNoField paths to include in results

Searchable Fields

Field NameTypeDescription
idstringThe unique identifier of the subscription
created_atstringThe date and time when the subscription was created
start_datestringThe date and time when the subscription starts
end_datestringThe date and time when the subscription ends
statusstringThe current status of the subscription
customerobjectThe customer associated with the subscription
planobjectThe plan associated with the subscription
current_billing_period_start_datestringThe start date of the current billing period
current_billing_period_end_datestringThe end date of the current billing period
auto_collectionbooleanWhether auto collection is enabled
net_termsintegerThe net terms for the subscription
metadataobjectAdditional metadata for the subscription
Response Schema
Field NameTypeDescription
hitsarrayList of matching records
hits[].idstringRecord identifier
hits[].scorenumberRelevance score
hits[].dataobjectRecord data containing the searchable fields listed above
hits[].data.idstringThe unique identifier of the subscription
hits[].data.created_atstringThe date and time when the subscription was created
hits[].data.start_datestringThe date and time when the subscription starts
hits[].data.end_datestringThe date and time when the subscription ends
hits[].data.statusstringThe current status of the subscription
hits[].data.customerobjectThe customer associated with the subscription
hits[].data.planobjectThe plan associated with the subscription
hits[].data.current_billing_period_start_datestringThe start date of the current billing period
hits[].data.current_billing_period_end_datestringThe end date of the current billing period
hits[].data.auto_collectionbooleanWhether auto collection is enabled
hits[].data.net_termsintegerThe net terms for the subscription
hits[].data.metadataobjectAdditional metadata for the subscription
next_cursorstring | nullCursor for next page of results
took_msnumberQuery execution time in milliseconds

Plans

Plans List

Returns a paginated list of plans

Python SDK

await orb.plans.list()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "plans",
"action": "list"
}'

Parameters

Parameter NameTypeRequiredDescription
limitintegerNoNumber of items to return per page
cursorstringNoCursor for pagination
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
namestring | null
descriptionstring | null
statusstring | null
default_invoice_memostring | null
net_termsinteger | null
currencystring | null
pricesarray | null
productobject | null
minimumobject | null
maximumobject | null
discountobject | null
trial_configobject | null
plan_phasesarray | null
external_plan_idstring | null
invoicing_currencystring | null
metadataobject | null

Meta

Field NameTypeDescription
next_cursorstring | null

Plans Get

Get a single plan by ID

Python SDK

await orb.plans.get(
plan_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "plans",
"action": "get",
"params": {
"plan_id": "<str>"
}
}'

Parameters

Parameter NameTypeRequiredDescription
plan_idstringYesPlan ID
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
namestring | null
descriptionstring | null
statusstring | null
default_invoice_memostring | null
net_termsinteger | null
currencystring | null
pricesarray | null
productobject | null
minimumobject | null
maximumobject | null
discountobject | null
trial_configobject | null
plan_phasesarray | null
external_plan_idstring | null
invoicing_currencystring | null
metadataobject | null

Search and filter plans records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await orb.plans.search(
query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "plans",
"action": "search",
"params": {
"query": {"filter": {"eq": {"id": "<str>"}}}
}
}'

Parameters

Parameter NameTypeRequiredDescription
queryobjectYesFilter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
query.filterobjectNoFilter conditions
query.sortarrayNoSort conditions
limitintegerNoMaximum results to return (default 1000)
cursorstringNoPagination cursor from previous response's next_cursor
fieldsarrayNoField paths to include in results

Searchable Fields

Field NameTypeDescription
idstringThe unique identifier of the plan
created_atstringThe date and time when the plan was created
namestringThe name of the plan
descriptionstringA description of the plan
statusstringThe status of the plan
currencystringThe currency of the plan
pricesarrayThe pricing options for the plan
productobjectThe product associated with the plan
external_plan_idstringThe external plan ID
metadataobjectAdditional metadata for the plan
Response Schema
Field NameTypeDescription
hitsarrayList of matching records
hits[].idstringRecord identifier
hits[].scorenumberRelevance score
hits[].dataobjectRecord data containing the searchable fields listed above
hits[].data.idstringThe unique identifier of the plan
hits[].data.created_atstringThe date and time when the plan was created
hits[].data.namestringThe name of the plan
hits[].data.descriptionstringA description of the plan
hits[].data.statusstringThe status of the plan
hits[].data.currencystringThe currency of the plan
hits[].data.pricesarrayThe pricing options for the plan
hits[].data.productobjectThe product associated with the plan
hits[].data.external_plan_idstringThe external plan ID
hits[].data.metadataobjectAdditional metadata for the plan
next_cursorstring | nullCursor for next page of results
took_msnumberQuery execution time in milliseconds

Invoices

Invoices List

Returns a paginated list of invoices

Python SDK

await orb.invoices.list()

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "invoices",
"action": "list"
}'

Parameters

Parameter NameTypeRequiredDescription
limitintegerNoNumber of items to return per page
cursorstringNoCursor for pagination
customer_idstringNoFilter invoices by customer ID
external_customer_idstringNoFilter invoices by external customer ID
subscription_idstringNoFilter invoices by subscription ID
invoice_date_gtstringNoFilter invoices with invoice date greater than this value (ISO 8601 format)
invoice_date_gtestringNoFilter invoices with invoice date greater than or equal to this value (ISO 8601 format)
invoice_date_ltstringNoFilter invoices with invoice date less than this value (ISO 8601 format)
invoice_date_ltestringNoFilter invoices with invoice date less than or equal to this value (ISO 8601 format)
status"draft" | "issued" | "paid" | "synced" | "void"NoFilter invoices by status
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
invoice_datestring | null
due_datestring | null
invoice_pdfstring | null
subtotalstring | null
totalstring | null
amount_duestring | null
statusstring | null
memostring | null
issue_failed_atstring | null
sync_failed_atstring | null
payment_failed_atstring | null
payment_started_atstring | null
voided_atstring | null
paid_atstring | null
issued_atstring | null
hosted_invoice_urlstring | null
line_itemsarray | null
subscriptionobject | null
customerobject | null
currencystring | null
discountobject | null
minimumobject | null
maximumobject | null
credit_notesarray | null
will_auto_issueboolean | null
eligible_to_issue_atstring | null
customer_balance_transactionsarray | null
auto_collectionobject | null
invoice_numberstring | null
billing_addressobject | any
shipping_addressobject | any
metadataobject | null

Meta

Field NameTypeDescription
next_cursorstring | null

Invoices Get

Get a single invoice by ID

Python SDK

await orb.invoices.get(
invoice_id="<str>"
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "invoices",
"action": "get",
"params": {
"invoice_id": "<str>"
}
}'

Parameters

Parameter NameTypeRequiredDescription
invoice_idstringYesInvoice ID
Response Schema

Records

Field NameTypeDescription
idstring
created_atstring | null
invoice_datestring | null
due_datestring | null
invoice_pdfstring | null
subtotalstring | null
totalstring | null
amount_duestring | null
statusstring | null
memostring | null
issue_failed_atstring | null
sync_failed_atstring | null
payment_failed_atstring | null
payment_started_atstring | null
voided_atstring | null
paid_atstring | null
issued_atstring | null
hosted_invoice_urlstring | null
line_itemsarray | null
subscriptionobject | null
customerobject | null
currencystring | null
discountobject | null
minimumobject | null
maximumobject | null
credit_notesarray | null
will_auto_issueboolean | null
eligible_to_issue_atstring | null
customer_balance_transactionsarray | null
auto_collectionobject | null
invoice_numberstring | null
billing_addressobject | any
shipping_addressobject | any
metadataobject | null

Search and filter invoices records powered by Airbyte's data sync. This often provides additional fields and operators beyond what the API natively supports, making it easier to narrow down results before performing further operations. Only available in hosted mode.

Python SDK

await orb.invoices.search(
query={"filter": {"eq": {"id": "<str>"}}}
)

API

curl --location 'https://api.airbyte.ai/api/v1/connectors/sources/{your_source_id}/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_auth_token}' \
--data '{
"entity": "invoices",
"action": "search",
"params": {
"query": {"filter": {"eq": {"id": "<str>"}}}
}
}'

Parameters

Parameter NameTypeRequiredDescription
queryobjectYesFilter and sort conditions. Supports operators: eq, neq, gt, gte, lt, lte, in, like, fuzzy, keyword, not, and, or
query.filterobjectNoFilter conditions
query.sortarrayNoSort conditions
limitintegerNoMaximum results to return (default 1000)
cursorstringNoPagination cursor from previous response's next_cursor
fieldsarrayNoField paths to include in results

Searchable Fields

Field NameTypeDescription
idstringThe unique identifier of the invoice
created_atstringThe date and time when the invoice was created
invoice_datestringThe date of the invoice
due_datestringThe due date for the invoice
invoice_pdfstringThe URL to download the PDF version of the invoice
subtotalstringThe subtotal amount of the invoice
totalstringThe total amount of the invoice
amount_duestringThe amount due on the invoice
statusstringThe current status of the invoice
memostringAny additional notes or comments on the invoice
paid_atstringThe date and time when the invoice was paid
issued_atstringThe date and time when the invoice was issued
hosted_invoice_urlstringThe URL to view the hosted invoice
line_itemsarrayThe line items on the invoice
subscriptionobjectThe subscription associated with the invoice
customerobjectThe customer associated with the invoice
currencystringThe currency of the invoice
invoice_numberstringThe invoice number
metadataobjectAdditional metadata for the invoice
Response Schema
Field NameTypeDescription
hitsarrayList of matching records
hits[].idstringRecord identifier
hits[].scorenumberRelevance score
hits[].dataobjectRecord data containing the searchable fields listed above
hits[].data.idstringThe unique identifier of the invoice
hits[].data.created_atstringThe date and time when the invoice was created
hits[].data.invoice_datestringThe date of the invoice
hits[].data.due_datestringThe due date for the invoice
hits[].data.invoice_pdfstringThe URL to download the PDF version of the invoice
hits[].data.subtotalstringThe subtotal amount of the invoice
hits[].data.totalstringThe total amount of the invoice
hits[].data.amount_duestringThe amount due on the invoice
hits[].data.statusstringThe current status of the invoice
hits[].data.memostringAny additional notes or comments on the invoice
hits[].data.paid_atstringThe date and time when the invoice was paid
hits[].data.issued_atstringThe date and time when the invoice was issued
hits[].data.hosted_invoice_urlstringThe URL to view the hosted invoice
hits[].data.line_itemsarrayThe line items on the invoice
hits[].data.subscriptionobjectThe subscription associated with the invoice
hits[].data.customerobjectThe customer associated with the invoice
hits[].data.currencystringThe currency of the invoice
hits[].data.invoice_numberstringThe invoice number
hits[].data.metadataobjectAdditional metadata for the invoice
next_cursorstring | nullCursor for next page of results
took_msnumberQuery execution time in milliseconds