WooCommerce REST API 文档

title: "客户 #" post_status: publish comment_status: open taxonomy: category: - woocommerce-rest-api post_tag: - V2 - Includes - Source

客户

本节列出了所有可用于创建、编辑或以其他方式操作客户的 API。

客户属性

Attribute Type Description
id integer Customer ID (user ID) read-only
created_at string UTC DateTime when the customer was created read-only
email string Customer email address mandatory
first_name string Customer first name
last_name string Customer last name
username string Customer username, can be generated automatically from the customer's email addrees if the option woocommerce_registration_generate_username is equal to yes cannot be changed
password string Customer password, can be generated automatically with wp_generate_password() if the "Automatically generate customer password" option is enabled, check the index meta for generate_password write-only
last_order_id integer Last order ID read-only
last_order_date string UTC DateTime of the customer last order read-only
orders_count integer Quantity of orders that the customer have read-only
total_spent integer Total amount spent read-only
avatar_url string Gravatar URL
billing_address array List of Billing Address fields. See Billing Address Properties
shipping_address array List of Shipping Address fields. See Shipping Address Properties

Billing Address Properties

Attribute Type Description
first_name string First name
last_name string Last name
company string Company name
address_1 string Address line 1
address_2 string Address line 2
city string City name
state string ISO code or name of the state, province or district
postcode string Postal code
country string ISO code of the country
email string Email address
phone string Phone

Shipping Address Properties

Attribute Type Description
first_name string First name
last_name string Last name
company string Company name
address_1 string Address line 1
address_2 string Address line 2
city string City name
state string ISO code or name of the state, province or district
postcode string Postal code
country string ISO code of the country

Create A Customer

This API helps you to create a new customer.

HTTP Request

POST
/wc-api/v2/customers
curl -X POST https://example.com/wc-api/v2/customers \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "customer": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    }
  }
}'

var data = {
  customer: {
    email: 'john.doe@example.com',
    first_name: 'John',
    last_name: 'Doe',
    username: 'john.doe',
    billing_address: {
      first_name: 'John',
      last_name: 'Doe',
      company: '',
      address_1: '969 Market',
      address_2: '',
      city: 'San Francisco',
      state: 'CA',
      postcode: '94103',
      country: 'US',
      email: 'john.doe@example.com',
      phone: '(555) 555-5555'
    },
    shipping_address: {
      first_name: 'John',
      last_name: 'Doe',
      company: '',
      address_1: '969 Market',
      address_2: '',
      city: 'San Francisco',
      state: 'CA',
      postcode: '94103',
      country: 'US'
    }
  }
};

WooCommerce.post('customers', data, function(err, data, res) {
  console.log(res);
});

data = {
    "customer": {
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "username": "john.doe",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company": "",
            "address_1": "969 Market",
            "address_2": "",
            "city": "San Francisco",
            "state": "CA",
            "postcode": "94103",
            "country": "US",
            "email": "john.doe@example.com",
            "phone": "(555) 555-5555"
        },
        "shipping_address": {
            "first_name": "John",
            "last_name": "Doe",
            "company": "",
            "address_1": "969 Market",
            "address_2": "",
            "city": "San Francisco",
            "state": "CA",
            "postcode": "94103",
            "country": "US"
        }
    }
}

print(wcapi.post("customers", data).json())

<?php
$data = array(
    'customer' => array(
        'email' => 'john.doe@example.com',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'username' => 'john.doe',
        'billing_address' => array(
            'first_name' => 'John',
            'last_name' => 'Doe',
            'company' => '',
            'address_1' => '969 Market',
            'address_2' => '',
            'city' => 'San Francisco',
            'state' => 'CA',
            'postcode' => '94103',
            'country' => 'US',
            'email' => 'john.doe@example.com',
            'phone' => '(555) 555-5555'
        ),
        'shipping_address' => array(
            'first_name' => 'John',
            'last_name' => 'Doe',
            'company' => '',
            'address_1' => '969 Market',
            'address_2' => '',
            'city' => 'San Francisco',
            'state' => 'CA',
            'postcode' => '94103',
            'country' => 'US'
        )
    )
);

print_r($woocommerce->customers->create($data));
?>

data = {
  customer: {
    email: "john.doe@example.com",
    first_name: "John",
    last_name: "Doe",
    username: "john.doe",
    billing_address: {
      first_name: "John",
      last_name: "Doe",
      company: "",
      address_1: "969 Market",
      address_2: "",
      city: "San Francisco",
      state: "CA",
      postcode: "94103",
      country: "US",
      email: "john.doe@example.com",
      phone: "(555) 555-5555"
    },
    shipping_address: {
      first_name: "John",
      last_name: "Doe",
      company: "",
      address_1: "969 Market",
      address_2: "",
      city: "San Francisco",
      state: "CA",
      postcode: "94103",
      country: "US"
    }
  }
}

woocommerce.post("customers", data).parsed_response

JSON response example:

{
  "customer": {
    "id": 2,
    "created_at": "2015-01-05T18:34:19Z",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "last_order_id": null,
    "last_order_date": null,
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    }
  }
}

查看客户

此 API 允许您通过 ID 或电子邮件检索并查看特定客户。

HTTP 请求

GET
/wc-api/v2/customers/<id>
GET
/wc-api/v2/customers/email/<email>
curl https://example.com/wc-api/v2/customers/2 \
    -u consumer_key:consumer_secret

WooCommerce.get('customers/2', function(err, data, res) {
  console.log(res);
});

print(wcapi.get("customers/2").json())

<?php print_r($woocommerce->customers->get(2)); ?>

woocommerce.get("customers/2").parsed_response

JSON 响应示例：

{
  "customer": {
    "id": 2,
    "created_at": "2015-01-05T18:34:19Z",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe",
    "last_order_id": null,
    "last_order_date": null,
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    }
  }
}

View List Of Customers

This API helps you to view all the customers.

HTTP Request

GET
/wc-api/v2/customers
curl https://example.com/wc-api/v2/customers \
    -u consumer_key:consumer_secret

WooCommerce.get('customers', function(err, data, res) {
  console.log(res);
});

print(wcapi.get("customers").json())

<?php print_r($woocommerce->customers->get()); ?>

woocommerce.get("customers").parsed_response

JSON response example:

{
  "customers": [
    {
      "id": 2,
      "created_at": "2015-01-05T18:34:19Z",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "username": "john.doe",
      "last_order_id": 123,
      "last_order_date": "2015-01-14T16:47:30Z",
      "orders_count": 10,
      "total_spent": "1034.58",
      "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
      "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      }
    },
    {
      "id": 3,
      "created_at": "2015-01-10T14:25:39Z",
      "email": "joao.silva@example.com",
      "first_name": "João",
      "last_name": "Silva",
      "username": "joao.silva",
      "last_order_id": 120,
      "last_order_date": "2015-01-10T14:26:30Z",
      "orders_count": 1,
      "total_spent": "429.00",
      "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
      "billing_address": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR",
        "email": "joao.silva@example.com",
        "phone": "(55) 5555-5555"
      },
      "shipping_address": {
        "first_name": "João",
        "last_name": "Silva",
        "company": "",
        "address_1": "Av. Brasil, 432",
        "address_2": "",
        "city": "Rio de Janeiro",
        "state": "RJ",
        "postcode": "12345-000",
        "country": "BR"
      }
    }
  ]
}

Available Filters

Filter Type Description
role string Customers by status. eg: customer or subscriber

更新客户信息

此 API 允许您修改客户信息。

HTTP 请求

PUT
/wc-api/v2/customers/<id>
curl -X PUT https://example.com/wc-api/v2/customers/2 \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "customer": {
    "first_name": "James",
    "billing_address": {
      "first_name": "James"
    },
    "shipping_address": {
      "first_name": "James"
    }
  }
}'

var data = {
  customer: {
    first_name: 'James',
    billing_address: {
      first_name: 'James'
    },
    shipping_address: {
      first_name: 'James'
    }
  }
};

WooCommerce.put('customers/2', data, function(err, data, res) {
  console.log(res);
});

data = {
    "customer": {
        "first_name": "James",
        "billing_address": {
            "first_name": "James"
        },
        "shipping_address": {
            "first_name": "James"
        }
    }
}

print(wcapi.put("customers/2", data).json())

<?php
$data = array(
    'customer' => array(
        'first_name' => 'James',
        'billing_address' => array(
            'first_name' => 'James'
        ),
        'shipping_address' => array(
            'first_name' => 'James'
        )
    )
);

print_r($woocommerce->customers->update(2, $data));
?>

data = {
  customer: {
    first_name: "James",
    billing_address: {
      first_name: "James"
    },
    shipping_address: {
      first_name: "James"
    }
  }
}

woocommerce.put("customers/2", data).parsed_response

JSON 响应示例：

{
  "customer": {
    "id": 2,
    "created_at": "2015-01-05T18:34:19Z",
    "email": "john.doe@example.com",
    "first_name": "James",
    "last_name": "Doe",
    "username": "john.doe",
    "last_order_id": null,
    "last_order_date": null,
    "orders_count": 0,
    "total_spent": "0.00",
    "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
    "billing_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US",
      "email": "john.doe@example.com",
      "phone": "(555) 555-5555"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "company": "",
      "address_1": "969 Market",
      "address_2": "",
      "city": "San Francisco",
      "state": "CA",
      "postcode": "94103",
      "country": "US"
    }
  }
}

Delete A Customer

This API helps you delete a customer.

HTTP Request

DELETE
/wc-api/v2/customers/<id>
curl -X DELETE https://example.com/wc-api/v2/customers/2 \
    -u consumer_key:consumer_secret

WooCommerce.delete('customers/2', function(err, data, res) {
  console.log(res);
});

print(wcapi.delete("customers/2").json())

<?php print_r($woocommerce->customers->delete(2)); ?>

woocommerce.delete("customers/2").parsed_response

JSON response example:

{
  "message": "Permanently deleted customer"
}

查看客户订单

此 API 允许您检索客户的订单。

HTTP 请求

GET
/wc-api/v2/customers/<id>/orders
curl https://example.com/wc-api/v2/customers/2/orders \
    -u consumer_key:consumer_secret

WooCommerce.get('customers/2/orders', function(err, data, res) {
  console.log(res);
});

print(wcapi.get("customers/2/orders").json())

<?php print_r($woocommerce->customers->get_orders(2)); ?>

woocommerce.get("customers/2/orders").parsed_response

JSON 响应示例：

{
  "orders": [
    {
      "id": 531,
      "order_number": 531,
      "created_at": "2015-01-21T12:02:13Z",
      "updated_at": "2015-01-21T12:02:13Z",
      "completed_at": "2015-01-21T12:02:13Z",
      "status": "on-hold",
      "currency": "USD",
      "total": "30.00",
      "subtotal": "20.00",
      "total_line_items_quantity": 1,
      "total_tax": "0.00",
      "total_shipping": "10.00",
      "cart_tax": "0.00",
      "shipping_tax": "0.00",
      "total_discount": "0.00",
      "shipping_methods": "Flat Rate",
      "payment_details": {
        "method_id": "bacs",
        "method_title": "Direct Bank Transfer",
        "paid": false
      },
      "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US",
        "email": "john.doe@example.com",
        "phone": "(555) 555-5555"
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "company": "",
        "address_1": "969 Market",
        "address_2": "",
        "city": "San Francisco",
        "state": "CA",
        "postcode": "94103",
        "country": "US"
      },
      "note": "",
      "customer_ip": "127.0.0.1",
      "customer_user_agent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:35.0) Gecko/20100101 Firefox/35.0",
      "customer_id": 2,
      "view_order_url": "https://example.com/my-account/view-order/531",
      "line_items": [
        {
          "id": 417,
          "subtotal": "20.00",
          "subtotal_tax": "0.00",
          "total": "20.00",
          "total_tax": "0.00",
          "price": "20.00",
          "quantity": 1,
          "tax_class": null,
          "name": "Premium Quality",
          "product_id": 19,
          "sku": "",
          "meta": []
        }
      ],
      "shipping_lines": [
        {
          "id": 418,
          "method_id": "flat_rate",
          "method_title": "Flat Rate",
          "total": "10.00"
        }
      ],
      "tax_lines": [],
      "fee_lines": [],
      "coupon_lines": [],
      "customer": {
        "id": 2,
        "created_at": "2014-11-19T18:34:19Z",
        "email": "john.doe@example.com",
        "first_name": "",
        "last_name": "",
        "username": "john.doe",
        "last_order_id": "531",
        "last_order_date": "2015-01-21T12:02:13Z",
        "orders_count": 1,
        "total_spent": "0.00",
        "avatar_url": "https://secure.gravatar.com/avatar/ad516503a11cd5ca435acc9bb6523536?s=96",
        "billing_address": {
          "first_name": "John",
          "last_name": "Doe",
          "company": "",
          "address_1": "969 Market",
          "address_2": "",
          "city": "San Francisco",
          "state": "CA",
          "postcode": "94103",
          "country": "US",
          "email": "john.doe@example.com",
          "phone": "(555) 555-5555"
        },
        "shipping_address": {
          "first_name": "John",
          "last_name": "Doe",
          "company": "",
          "address_1": "969 Market",
          "address_2": "",
          "city": "San Francisco",
          "state": "CA",
          "postcode": "94103",
          "country": "US"
        }
      }
    }
  ]
}

查看客户下载记录

此 API 允许您检索客户的下载记录。

HTTP 请求

GET
/wc-api/v2/customers/<id>/downloads
curl https://example.com/wc-api/v2/customers/2/downloads \
    -u consumer_key:consumer_secret

WooCommerce.get('customers/2/downloads', function(err, data, res) {
  console.log(res);
});

print(wcapi.get("customers/2/downloads").json())

<?php print_r($woocommerce->customers->get_downloads(2)); ?>

woocommerce.get("customers/2/downloads").parsed_response

JSON 响应示例：

{
  "downloads": [
    {
      "download_url": "https://example.com/?download_file=96&order=wc_order_9999999999999&email=john.doe@example.com&key=99999999999999999999999999999999",
      "download_id": "99999999999999999999999999999999",
      "product_id": 96,
      "download_name": "Woo Album #4 &ndash; Woo Album",
      "order_id": 532,
      "order_key": "wc_order_9999999999999",
      "downloads_remaining": "5",
      "access_expires": null,
      "file": {
        "name": "Woo Album",
        "file": "http://example.com/wp-content/uploads/woocommerce_uploads/2015/01/album.zip"
      }
    }
  ]
}

Customer Downloads Properties

Attribute Type Description
download_url string Download file URL
download_id string Download ID
product_id integer Downloadable product ID
download_name string Downloadable file name
order_id integer Order ID
order_key string Order Key
downloads_remaining string Amount of downloads remaining. An empty string means that is "Unlimited"
access_expires string UTC DateTime when the download access expires. null means "Never"
file array List for downloadable files, each one have a name (file name) and file (file URL) attribute

查看客户数量

此 API 允许您检索所有客户的数量。

HTTP 请求

GET
/wc-api/v2/customers/count
curl https://example.com/wc-api/v2/customers/count \
    -u consumer_key:consumer_secret

WooCommerce.get('customers/count', function(err, data, res) {
  console.log(res);
});

print(wcapi.get("customers/count").json())

<?php print_r($woocommerce->customers->get_count()); ?>

woocommerce.get("customers/count").parsed_response

JSON 响应示例：

{
  "count": 10
}

Available Filters

Filter Type Description
role string Customers by status. eg: customer or subscriber