Skip to main content

List customers​

This endpoint returns a list of all customers for an account. The list of customers is ordered starting from the most recently created customer. This endpoint follows Orb's standardized pagination format.

See Customer for an overview of the customer model.

Query Parameters
    limit integer

    Possible values: >= 1 and <= 1000

    Default value: 20

    cursor string
    created_at[gte] date-time
    created_at[gt] date-time
    created_at[lt] date-time
    created_at[lte] date-time
Responses

OK

Response Headers
    Schema
      data object[] required
    • Array [
      • 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.

      property name* string
      id string required
      external_customer_id string nullable 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 nullable 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 string nullable required

      Possible values: [quickbooks, bill.com, stripe_charge, stripe_invoice, netsuite]

      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.

      created_at date-time required
      shipping_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      billing_address object nullable
      line1 string nullable required
      line2 string nullable required
      city string nullable required
      state string nullable required
      postal_code string nullable required
      country string nullable required
      balance string required

      The customer's current balance in their currency.

      currency string nullable required
      tax_id object nullable

      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​

      CountryTypeDescription
      Andorraad_nrtAndorran NRT Number
      Argentinaar_cuitArgentinian Tax ID Number
      Australiaau_abnAustralian Business Number (AU ABN)
      Australiaau_arnAustralian Taxation Office Reference Number
      Austriaeu_vatEuropean VAT Number
      Bahrainbh_vatBahraini VAT Number
      Belgiumeu_vatEuropean VAT Number
      Boliviabo_tinBolivian Tax ID
      Brazilbr_cnpjBrazilian CNPJ Number
      Brazilbr_cpfBrazilian CPF Number
      Bulgariabg_uicBulgaria Unified Identification Code
      Bulgariaeu_vatEuropean VAT Number
      Canadaca_bnCanadian BN
      Canadaca_gst_hstCanadian GST/HST Number
      Canadaca_pst_bcCanadian PST Number (British Columbia)
      Canadaca_pst_mbCanadian PST Number (Manitoba)
      Canadaca_pst_skCanadian PST Number (Saskatchewan)
      Canadaca_qstCanadian QST Number (Québec)
      Chilecl_tinChilean TIN
      Chinacn_tinChinese Tax ID
      Colombiaco_nitColombian NIT Number
      Costa Ricacr_tinCosta Rican Tax ID
      Croatiaeu_vatEuropean VAT Number
      Cypruseu_vatEuropean VAT Number
      Czech Republiceu_vatEuropean VAT Number
      Denmarkeu_vatEuropean VAT Number
      Dominican Republicdo_rcnDominican RCN Number
      Ecuadorec_rucEcuadorian RUC Number
      Egypteg_tinEgyptian Tax Identification Number
      El Salvadorsv_nitEl Salvadorian NIT Number
      Estoniaeu_vatEuropean VAT Number
      EUeu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
      Finlandeu_vatEuropean VAT Number
      Franceeu_vatEuropean VAT Number
      Georgiage_vatGeorgian VAT
      Germanyeu_vatEuropean VAT Number
      Greeceeu_vatEuropean VAT Number
      Hong Konghk_brHong Kong BR Number
      Hungaryeu_vatEuropean VAT Number
      Hungaryhu_tinHungary Tax Number (adószám)
      Icelandis_vatIcelandic VAT
      Indiain_gstIndian GST Number
      Indonesiaid_npwpIndonesian NPWP Number
      Irelandeu_vatEuropean VAT Number
      Israelil_vatIsrael VAT
      Italyeu_vatEuropean VAT Number
      Japanjp_cnJapanese Corporate Number (Hōjin Bangō)
      Japanjp_rnJapanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
      Japanjp_trnJapanese Tax Registration Number (Tōroku Bangō)
      Kazakhstankz_binKazakhstani Business Identification Number
      Kenyake_pinKenya Revenue Authority Personal Identification Number
      Latviaeu_vatEuropean VAT Number
      Liechtensteinli_uidLiechtensteinian UID Number
      Lithuaniaeu_vatEuropean VAT Number
      Luxembourgeu_vatEuropean VAT Number
      Malaysiamy_frpMalaysian FRP Number
      Malaysiamy_itnMalaysian ITN
      Malaysiamy_sstMalaysian SST Number
      Maltaeu_vat European VAT Number
      Mexicomx_rfcMexican RFC Number
      Netherlandseu_vatEuropean VAT Number
      New Zealandnz_gstNew Zealand GST Number
      Nigeriang_tinNigerian Tax Identification Number
      Norwayno_vatNorwegian VAT Number
      Norwayno_voecNorwegian VAT on e-commerce Number
      Omanom_vatOmani VAT Number
      Perupe_rucPeruvian RUC Number
      Philippinesph_tin Philippines Tax Identification Number
      Polandeu_vatEuropean VAT Number
      Portugaleu_vatEuropean VAT Number
      Romaniaeu_vatEuropean VAT Number
      Romaniaro_tinRomanian Tax ID Number
      Russiaru_innRussian INN
      Russiaru_kppRussian KPP
      Saudi Arabiasa_vatSaudi Arabia VAT
      Serbiars_pibSerbian PIB Number
      Singaporesg_gstSingaporean GST
      Singaporesg_uenSingaporean UEN
      Slovakiaeu_vatEuropean VAT Number
      Sloveniaeu_vatEuropean VAT Number
      Sloveniasi_tinSlovenia Tax Number (davčna številka)
      South Africaza_vatSouth African VAT Number
      South Koreakr_brnKorean BRN
      Spaines_cifSpanish NIF Number (previously Spanish CIF Number)
      Spaineu_vatEuropean VAT Number
      Swedeneu_vatEuropean VAT Number
      Switzerlandch_vatSwitzerland VAT Number
      Taiwantw_vatTaiwanese VAT
      Thailandth_vatThai VAT
      Turkeytr_tinTurkish Tax Identification Number
      Ukraineua_vatUkrainian VAT
      United Arab Emiratesae_trnUnited Arab Emirates TRN
      United Kingdomeu_vatNorthern Ireland VAT Number
      United Kingdomgb_vatUnited Kingdom VAT Number
      United Statesus_einUnited States EIN
      Uruguayuy_rucUruguayan RUC Number
      Venezuelave_rifVenezuelan RIF Number
      Vietnamvn_tinVietnamese Tax ID Number
      country string required

      Possible values: [AD, AE, AR, AT, AU, BE, BG, BH, BO, BR, CA, CH, CL, CN, CO, CR, CY, CZ, DE, DK, EE, DO, EC, EG, ES, EU, FI, FR, GB, GE, GR, HK, HR, HU, ID, IE, IL, IN, IS, IT, JP, KE, KR, KZ, LI, LT, LU, LV, MT, MX, MY, NG, NL, NO, NZ, OM, PE, PH, PL, PT, RO, RS, RU, SA, SE, SG, SI, SK, SV, TH, TR, TW, UA, US, UY, VE, VN, ZA]

      type string required

      Possible values: [ad_nrt, ae_trn, ar_cuit, eu_vat, au_abn, au_arn, bg_uic, bh_vat, bo_tin, br_cnpj, br_cpf, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, ch_vat, cl_tin, cn_tin, co_nit, cr_tin, do_rcn, ec_ruc, eg_tin, es_cif, eu_oss_vat, gb_vat, ge_vat, hk_br, hu_tin, id_npwp, il_vat, in_gst, is_vat, jp_cn, jp_rn, jp_trn, ke_pin, kr_brn, kz_bin, li_uid, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, nz_gst, om_vat, pe_ruc, ph_tin, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sv_nit, th_vat, tr_tin, tw_vat, ua_vat, us_ein, uy_ruc, ve_rif, vn_tin, za_vat]

      value string required
      auto_collection boolean required
      exempt_from_automated_tax boolean nullable required
      email_delivery boolean required
      additional_emails string[] required
      portal_url string nullable required
      accounting_sync_configuration object nullable
      excluded boolean required
      accounting_providers object[] required
    • Array [
      • provider_type string required

      Possible values: [quickbooks, netsuite]

      external_provider_id string nullable required
    • ]
      • reporting_configuration object nullable
      exempt boolean required
    • ]
      • pagination_metadata object required
      has_more boolean required
      next_cursor string nullable required
    Loading...