メインコンテンツへスキップ

顧客

顧客オブジェクトを使用すると、ビジネスがサービスを提供する顧客を作成および管理できます。連絡先の詳細、住所、請求履歴などの重要な情報を保存し、これらはサブスクリプションの作成や支払いの処理に不可欠です。

顧客オブジェクト

顧客オブジェクトは、システム内の一意の顧客を表します。

AttributeTypeDescription
idstring顧客オブジェクトの一意の識別子。cus_で始まります。
didstring顧客の分散型識別子（DID）。
livemodebooleanオブジェクトがライブモードで存在する場合はtrue、テストモードで存在する場合はfalse。
namestring顧客の氏名。
emailstring顧客の主要なメールアドレス。
phonestring顧客の主要な電話番号。
addressobject顧客の請求先住所。以下のアドレスオブジェクトのプロパティを参照してください。
balancestring顧客の現在のクレジット残高。
delinquentboolean顧客に支払い期限を過ぎた請求があるかどうか。
metadataobjectオブジェクトに添付できるキーと値のペアのセット。
created_atstring顧客が作成されたときのタイムスタンプ。
updated_atstring顧客オブジェクトが最後に更新されたときのタイムスタンプ。

アドレスオブジェクトのプロパティ

AttributeTypeDescription
countrystring2文字の国コード（ISO 3166-1 alpha-2）。
statestring州、省、県、または地域。
citystring市、区、郊外、町、または村。
line1string住所1（例：通り、私書箱、会社名）。
line2string住所2（例：アパート、スイート、ユニット、建物）。
postal_codestring郵便番号。

顧客の取得

一意のIDまたはDIDを指定して、既存の顧客の詳細を取得します。

パラメータ

NameTypeDescription
idstring取得する顧客の識別子（cus_...またはDID）。

戻り値

指定されたIDを持つ顧客が存在する場合、TCustomerExpandedオブジェクトを返します。

例

Retrieve a Customer

javascript
async function retrieveCustomer(customerId) {
  try {
    const customer = await payment.customers.retrieve(customerId);
    console.log('Retrieved customer:', customer);
    return customer;
  } catch (error) {
    console.error('Error retrieving customer:', error.message);
  }
}

// Example usage with a customer ID
retrieveCustomer('cus_xxxxxxxxxxxxxxxx');

レスポンスの例

Example Customer Object

json
{
  "id": "cus_xxxxxxxxxxxxxxxx",
  "did": "zNK...",
  "livemode": true,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+15551234567",
  "address": {
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "postal_code": "94105"
  },
  "balance": "100.00",
  "delinquent": false,
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

顧客の更新

渡されたパラメータの値を設定して、指定された顧客を更新します。指定されなかったパラメータは変更されません。

パラメータ

NameTypeDescription
idstring更新する顧客の識別子。
dataobject更新するフィールドを含むオブジェクト。詳細は以下を参照してください。

データオブジェクトのプロパティ

AttributeTypeDescription
namestring顧客の氏名。
emailstring顧客のメールアドレス。
phonestring顧客の電話番号。
addressobject顧客の請求先住所。アドレスオブジェクトの構造に従います。
metadataobject顧客と共に保存するキーと値のペアのセット。

戻り値

更新されたTCustomerオブジェクトを返します。

例

Update a Customer

javascript
async function updateCustomerDetails(customerId) {
  try {
    const updatedCustomer = await payment.customers.update(customerId, {
      email: 'john.new.doe@example.com',
      metadata: {
        internal_id: 'user-456'
      }
    });
    console.log('Customer updated successfully:', updatedCustomer);
    return updatedCustomer;
  } catch (error) {
    console.error('Error updating customer:', error.message);
  }
}

updateCustomerDetails('cus_xxxxxxxxxxxxxxxx');

全顧客の一覧表示

顧客のページ分割されたリストを返します。

パラメータ

NameTypeDescription
paramsobjectページネーションおよびフィルタリングパラメータを含むオブジェクト。

Paramsオブジェクトのプロパティ

AttributeTypeDescription
didstring任意。特定のDIDを持つ顧客にリストをフィルタリングします。
pagenumber任意。取得するページ番号。デフォルトは1です。
pageSizenumber任意。1ページあたりに取得する顧客数。デフォルトは20です。

戻り値

TCustomerExpandedオブジェクトのlistとページネーション詳細を含むページ分割されたオブジェクトを返します。

例

List Customers

javascript
async function listCustomers() {
  try {
    const response = await payment.customers.list({ pageSize: 5 });
    console.log(`Total customers: ${response.count}`);
    console.log('First page of customers:', response.list);
    return response;
  } catch (error) {
    console.error('Error listing customers:', error.message);
  }
}

listCustomers();

レスポンスの例

Paginated Customer List

json
{
  "count": 50,
  "list": [
    {
      "id": "cus_xxxxxxxxxxxxxxxx",
      "did": "zNK...",
      "name": "John Doe",
      "email": "john.doe@example.com",
      // ... other customer fields
    }
    // ... more customer objects
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

顧客の検索

検索クエリに一致する顧客のページ分割されたリストを返します。検索は名前、メールアドレス、DIDなどのフィールドに対して実行されます。

パラメータ

NameTypeDescription
paramsobject検索およびページネーションパラメータを含むオブジェクト。

Paramsオブジェクトのプロパティ

AttributeTypeDescription
querystring検索文字列。
pagenumber任意。取得するページ番号。デフォルトは1です。
pageSizenumber任意。1ページあたりに取得する顧客数。デフォルトは20です。

戻り値

検索クエリに一致するTCustomerExpandedオブジェクトのlistを含むページ分割されたオブジェクトを返します。

例

Search for Customers

javascript
async function searchForCustomer(query) {
  try {
    const results = await payment.customers.search({ query: query });
    console.log(`Found ${results.count} customer(s) matching '${query}':`, results.list);
    return results;
  } catch (error) {
    console.error('Error searching for customers:', error.message);
  }
}

searchForCustomer('john.doe');

延滞請求書の取得

特定の顧客の回収不能な請求書のリストを、通貨ごとにグループ化された支払期日総額の要約と共に取得します。

パラメータ

NameTypeDescription
idstring顧客の識別子。

戻り値

顧客、その延滞請求書のリスト、および支払期日額の要約を含むオブジェクト。

例

Get Overdue Invoices

javascript
async function getOverdueInvoices(customerId) {
  try {
    const overdueData = await payment.customers.overdueInvoices(customerId);
    console.log('Overdue invoices data:', overdueData);
    return overdueData;
  } catch (error) {
    console.error('Error retrieving overdue invoices:', error.message);
  }
}

getOverdueInvoices('cus_xxxxxxxxxxxxxxxx');

レスポンスの例

Overdue Invoices Response

json
{
  "customer": {
    "id": "cus_xxxxxxxxxxxxxxxx",
    // ... customer details
  },
  "invoices": [
    {
      "id": "in_yyyyyyyyyyyyyyyy",
      "status": "uncollectible",
      "amount_remaining": "2500",
      "currency_id": "curr_zzzzzzzzzzzzzzzz",
      // ... other invoice details
    }
  ],
  "summary": {
    "curr_zzzzzzzzzzzzzzzz": {
      "amount": "2500",
      "currency": {
        // ... payment currency details
      },
      "method": {
        // ... payment method details
      }
    }
  }
}