Skip to main content
GET
Fetch customer

Authorizations

Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Path Parameters

customer_id
string
required

Response

OK

A customer is a buyer of your products, and the other party to the billing relationship.

In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an external_customer_id with your own identifier. See Customer ID Aliases for further information about how these aliases work in Orb.

In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the payment_provider_id and the payment_provider enum field to express this mapping.

A customer also has a timezone (from the standard IANA timezone database), which defaults to your account's timezone. See Timezone localization for information on what this timezone parameter influences within Orb.

metadata
Metadata · object
required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

id
string
required
external_customer_id
string | null
required

An optional user-defined ID for this customer resource, used throughout the system as an alias for this Customer. Use this field to identify a customer by an existing identifier in your system.

name
string
required

The full name of the customer

email
string
required

A valid customer email, to be used for notifications. When Orb triggers payment through a payment gateway, this email will be used for any automatically issued receipts.

timezone
string
required

A timezone identifier from the IANA timezone database, such as "America/Los_Angeles". This "defaults to your account's timezone if not set. This cannot be changed after customer creation.

payment_provider_id
string | null
required

The ID of this customer in an external payments solution, such as Stripe. This is used for creating charges or invoices in the external system via Orb.

payment_provider
enum<string> | null
required

This is used for creating charges or invoices in an external system via Orb. When not in test mode, the connection must first be configured in the Orb webapp.

Available options:
quickbooks,
bill.com,
stripe_charge,
stripe_invoice,
netsuite,
adyen
created_at
string<date-time>
required
shipping_address
Address · object | null
required
billing_address
Address · object | null
required
balance
string
required

The customer's current balance in their currency.

currency
string | null
required
tax_id
CustomerTaxId · object | null
required

Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.

Supported Tax ID Countries and Types

auto_collection
boolean
required
exempt_from_automated_tax
boolean | null
required
email_delivery
boolean
required
auto_issuance
boolean | null
required

Whether invoices for this customer should be automatically issued. If true, invoices will be automatically issued. If false, invoices will require manual approval. If null, inherits the account-level setting.

additional_emails
string[]
required
portal_url
string | null
required

Deprecated. Returns the URL of the most recent non-expired portal link, or null. When the account has opted into customer portal sessions, this field always returns null. Use POST /v1/customers/{id}/portal_sessions to mint short-lived portal session URLs.

hierarchy
CustomerHierarchy · object
required

The hierarchical relationships for this customer.

accounting_sync_configuration
AccountingSyncConfiguration · object | null
reporting_configuration
ReportingConfiguration · object | null
payment_configuration
PaymentConfiguration · object | null

Payment configuration for the customer, applicable when using Orb Invoicing with a supported payment provider such as Stripe.

default_payment_method
PaymentMethod · object | null

The customer's default payment method, or null if none is set.

automatic_tax_enabled
boolean | null

Whether automatic tax calculation is enabled for this customer. This field is nullable for backwards compatibility but will always return a boolean value.