优惠券

优惠券 API 允许您创建、查看、更新和删除单个或一批优惠券代码。

优惠券属性

Attribute	Type	Description
id	integer	Unique identifier for the object. READ-ONLY
code	string	Coupon code. MANDATORY
amount	string	The amount of discount. Should always be numeric, even if setting a percentage.
date_created	date-time	The date the coupon was created, in the site's timezone. READ-ONLY
date_created_gmt	date-time	The date the coupon was created, as GMT. READ-ONLY
date_modified	date-time	The date the coupon was last modified, in the site's timezone. READ-ONLY
date_modified_gmt	date-time	The date the coupon was last modified, as GMT. READ-ONLY
discount_type	string	Determines the type of discount that will be applied. Options: percent, fixed_cart and fixed_product. Default is fixed_cart.
description	string	Coupon description.
date_expires	string	The date the coupon expires, in the site's timezone.
date_expires_gmt	string	The date the coupon expires, as GMT.
usage_count	integer	Number of times the coupon has been used already. READ-ONLY
individual_use	boolean	If true, the coupon can only be used individually. Other applied coupons will be removed from the cart. Default is false.
product_ids	array	List of product IDs the coupon can be used on.
excluded_product_ids	array	List of product IDs the coupon cannot be used on.
usage_limit	integer	How many times the coupon can be used in total.
usage_limit_per_user	integer	How many times the coupon can be used per customer.
limit_usage_to_x_items	integer	Max number of items in the cart the coupon can be applied to.
free_shipping	boolean	If true and if the free shipping method requires a coupon, this coupon will enable free shipping. Default is false.
product_categories	array	List of category IDs the coupon applies to.
excluded_product_categories	array	List of category IDs the coupon does not apply to.
exclude_sale_items	boolean	If true, this coupon will not be applied to items that have sale prices. Default is false.
minimum_amount	string	Minimum order amount that needs to be in the cart before coupon applies.
maximum_amount	string	Maximum order amount allowed when using the coupon.
email_restrictions	array	List of email addresses that can use this coupon.
used_by	array	List of user IDs (or guest email addresses) that have used the coupon. READ-ONLY
meta_data	array	Meta data. See Coupon - Meta data properties

Coupon - Meta data properties

Attribute	Type	Description
id	integer	Meta ID. READ-ONLY
key	string	Meta key.
value	string	Meta value.

创建优惠券

这个 API 可以帮助您创建新的优惠券。

POST /wp-json/wc/v3/coupons

cURL

curl -X POST https://example.com/wp-json/wc/v3/coupons \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "code": "10off",
  "discount_type": "percent",
  "amount": "10",
  "individual_use": true,
  "exclude_sale_items": true,
  "minimum_amount": "100.00"
}'

JavaScript

const data = {
	code: '10off',
	discount_type: 'percent',
	amount: '10',
	individual_use: true,
	exclude_sale_items: true,
	minimum_amount: '100.00',
};

WooCommerce.post( 'coupons', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php
$data = [
    'code' => '10off',
    'discount_type' => 'percent',
    'amount' => '10',
    'individual_use' => true,
    'exclude_sale_items' => true,
    'minimum_amount' => '100.00'
];

print_r($woocommerce->post('coupons', $data));
?>

Python

data = {
    "code": "10off",
    "discount_type": "percent",
    "amount": "10",
    "individual_use": True,
    "exclude_sale_items": True,
    "minimum_amount": "100.00"
}

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

Ruby

data = {
  code: "10off",
  discount_type: "percent",
  amount: "10",
  individual_use: true,
  exclude_sale_items: true,
  minimum_amount: "100.00"
}

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

JSON Response

{
	"id": 719,
	"code": "10off",
	"amount": "10.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:23:00",
	"date_modified_gmt": "2017-03-21T18:23:00",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}

获取优惠券

此 API 允许您通过编号获取并查看特定的优惠券。

GET /wp-json/wc/v3/coupons/<id>

cURL

curl https://example.com/wp-json/wc/v3/coupons/719 \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.get( 'coupons/719' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php print_r($woocommerce->get('coupons/719')); ?>

Python

print(wcapi.get("coupons/719").json())

Ruby

woocommerce.get("coupons/719").parsed_response

JSON Response

{
	"id": 719,
	"code": "10off",
	"amount": "10.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:23:00",
	"date_modified_gmt": "2017-03-21T18:23:00",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}

列出所有优惠券

此 API 帮助您列出所有已创建的优惠券。

GET /wp-json/wc/v3/coupons

cURL

curl https://example.com/wp-json/wc/v3/coupons \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.get( 'coupons' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

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

Python

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

Ruby

woocommerce.get("coupons").parsed_response

JSON Response

[
	{
		"id": 720,
		"code": "free shipping",
		"amount": "0.00",
		"date_created": "2017-03-21T15:25:02",
		"date_created_gmt": "2017-03-21T18:25:02",
		"date_modified": "2017-03-21T15:25:02",
		"date_modified_gmt": "2017-03-21T18:25:02",
		"discount_type": "fixed_cart",
		"description": "",
		"date_expires": null,
		"date_expires_gmt": null,
		"usage_count": 0,
		"individual_use": true,
		"product_ids": [],
		"excluded_product_ids": [],
		"usage_limit": null,
		"usage_limit_per_user": null,
		"limit_usage_to_x_items": null,
		"free_shipping": true,
		"product_categories": [],
		"excluded_product_categories": [],
		"exclude_sale_items": false,
		"minimum_amount": "0.00",
		"maximum_amount": "0.00",
		"email_restrictions": [],
		"used_by": [],
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons/720"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons"
				}
			]
		}
	},
	{
		"id": 719,
		"code": "10off",
		"amount": "10.00",
		"date_created": "2017-03-21T15:23:00",
		"date_created_gmt": "2017-03-21T18:23:00",
		"date_modified": "2017-03-21T15:23:00",
		"date_modified_gmt": "2017-03-21T18:23:00",
		"discount_type": "percent",
		"description": "",
		"date_expires": null,
		"date_expires_gmt": null,
		"usage_count": 0,
		"individual_use": true,
		"product_ids": [],
		"excluded_product_ids": [],
		"usage_limit": null,
		"usage_limit_per_user": null,
		"limit_usage_to_x_items": null,
		"free_shipping": false,
		"product_categories": [],
		"excluded_product_categories": [],
		"exclude_sale_items": true,
		"minimum_amount": "100.00",
		"maximum_amount": "0.00",
		"email_restrictions": [],
		"used_by": [],
		"meta_data": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons/719"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/coupons"
				}
			]
		}
	}
]

Available parameters

Parameter	Type	Description
context	string	Scope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
page	integer	Current page of the collection. Default is 1.
per_page	integer	Maximum number of items to be returned in result set. Default is 10.
search	string	Limit results to those matching a string.
after	string	Limit response to resources published after a given ISO8601 compliant date.
before	string	Limit response to resources published before a given ISO8601 compliant date.
modified_after	string	Limit response to resources modified after a given ISO8601 compliant date.
modified_before	string	Limit response to resources modified after a given ISO8601 compliant date.
dates_are_gmt	boolean	Whether to interpret dates as GMT when limiting response by published or modified date.
exclude	array	Ensure result set excludes specific IDs.
include	array	Limit result set to specific ids.
offset	integer	Offset the result set by a specific number of items.
order	string	Order sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderby	string	Sort collection by object attribute. Options: date, modified, id, include, title and slug. Default is date.
code	string	Limit result set to resources with a specific code.

Update a coupon

This API lets you make changes to a coupon.

PUT /wp-json/wc/v3/coupons/<id>

cURL

curl -X PUT https://example.com/wp-json/wc/v3/coupons/719 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "5"
}'

JavaScript

const data = {
	amount: '5',
};

WooCommerce.put( 'coupons/719', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php
$data = [
    'amount' => '5'
];

print_r($woocommerce->put('coupons/719', $data));
?>

Python

data = {
    "amount": "5"
}

print(wcapi.put("coupons/719", data).json())

Ruby

data = {
  amount: "5"
}

woocommerce.put("coupons/719", data).parsed_response

JSON Response

{
	"id": 719,
	"code": "10off",
	"amount": "5.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:26:16",
	"date_modified_gmt": "2017-03-21T18:26:16",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}

删除优惠券

此 API 可以帮助您删除一个优惠券。

DELETE /wp-json/wc/v3/coupons/<id>

cURL

curl -X DELETE https://example.com/wp-json/wc/v3/coupons/719?force=true \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.delete( 'coupons/719', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php print_r($woocommerce->delete('coupons/719', ['force' => true])); ?>

Python

print(wcapi.delete("coupons/719", params={"force": True}).json())

Ruby

woocommerce.delete("coupons/719", force: true).parsed_response

JSON Response

{
	"id": 719,
	"code": "10off",
	"amount": "5.00",
	"date_created": "2017-03-21T15:23:00",
	"date_created_gmt": "2017-03-21T18:23:00",
	"date_modified": "2017-03-21T15:26:16",
	"date_modified_gmt": "2017-03-21T18:26:16",
	"discount_type": "percent",
	"description": "",
	"date_expires": null,
	"date_expires_gmt": null,
	"usage_count": 0,
	"individual_use": true,
	"product_ids": [],
	"excluded_product_ids": [],
	"usage_limit": null,
	"usage_limit_per_user": null,
	"limit_usage_to_x_items": null,
	"free_shipping": false,
	"product_categories": [],
	"excluded_product_categories": [],
	"exclude_sale_items": true,
	"minimum_amount": "100.00",
	"maximum_amount": "0.00",
	"email_restrictions": [],
	"used_by": [],
	"meta_data": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons/719"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/coupons"
			}
		]
	}
}

可用参数

参数	类型	描述
force	字符串	使用 true 是否永久删除优惠券，默认值为 false。

批量更新优惠券

此 API 可以帮助您批量创建、更新和删除多个优惠券。

备注

注意：默认情况下，限制为最多可以创建、更新或删除 100 个对象。

POST /wp-json/wc/v3/coupons/batch

cURL

curl -X POST https://example.com/wp-json/wc/v3/coupons/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "code": "20off",
      "discount_type": "percent",
      "amount": "20",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    },
    {
      "code": "30off",
      "discount_type": "percent",
      "amount": "30",
      "individual_use": true,
      "exclude_sale_items": true,
      "minimum_amount": "100.00"
    }
  ],
  "update": [
    {
      "id": 719,
      "minimum_amount": "50.00"
    }
  ],
  "delete": [
    720
  ]
}'

JavaScript

const data = {
	create: [
		{
			code: '20off',
			discount_type: 'percent',
			amount: '20',
			individual_use: true,
			exclude_sale_items: true,
			minimum_amount: '100.00',
		},
		{
			code: '30off',
			discount_type: 'percent',
			amount: '30',
			individual_use: true,
			exclude_sale_items: true,
			minimum_amount: '100.00',
		},
	],
	update: [
		{
			id: 719,
			minimum_amount: '50.00',
		},
	],
	delete: [ 720 ],
};

WooCommerce.post( 'coupons/batch', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php
$data = [
    'create' => [
        [
            'code' => '20off',
            'discount_type' => 'percent',
            'amount' => '20',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ],
        [
            'code' => '30off',
            'discount_type' => 'percent',
            'amount' => '30',
            'individual_use' => true,
            'exclude_sale_items' => true,
            'minimum_amount' => '100.00'
        ]
    ],
    'update' => [
        [
            'id' => 719,
            'minimum_amount' => '50.00'
        ]
    ],
    'delete' => [
        720
    ]
];

print_r($woocommerce->post('coupons/batch', $data));
?>

Python

data = {
    "create": [
        {
            "code": "20off",
            "discount_type": "percent",
            "amount": "20",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        },
        {
            "code": "30off",
            "discount_type": "percent",
            "amount": "30",
            "individual_use": True,
            "exclude_sale_items": True,
            "minimum_amount": "100.00"
        }
    ],
    "update": [
        {
            "id": 719,
            "minimum_amount": "50.00"
        }
    ],
    "delete": [
        720
    ]
}

print(wcapi.post("coupons/batch", data).json())

Ruby

data = {
  create: [
    {
      code: "20off",
      discount_type: "percent",
      amount: "20",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    },
    {
      code: "30off",
      discount_type: "percent",
      amount: "30",
      individual_use: true,
      exclude_sale_items: true,
      minimum_amount: "100.00"
    }
  ],
  update: [
    {
      id: 719,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    720
  ]
}

woocommerce.post("coupons/batch", data).parsed_response

JSON Response

{
	"create": [
		{
			"id": 721,
			"code": "20off",
			"amount": "20.00",
			"date_created": "2017-03-21T15:27:29",
			"date_created_gmt": "2017-03-21T18:27:29",
			"date_modified": "2017-03-21T15:27:29",
			"date_modified_gmt": "2017-03-21T18:27:29",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "100.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/721"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		},
		{
			"id": 722,
			"code": "30off",
			"amount": "30.00",
			"date_created": "2017-03-21T15:27:31",
			"date_created_gmt": "2017-03-21T18:27:31",
			"date_modified": "2017-03-21T15:27:31",
			"date_modified_gmt": "2017-03-21T18:27:31",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "100.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/722"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	],
	"update": [
		{
			"id": 719,
			"code": "10off",
			"amount": "5.00",
			"date_created": "2017-03-21T15:23:00",
			"date_created_gmt": "2017-03-21T18:23:00",
			"date_modified": "2017-03-21T15:27:32",
			"date_modified_gmt": "2017-03-21T18:27:32",
			"discount_type": "percent",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": false,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": true,
			"minimum_amount": "50.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/719"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	],
	"delete": [
		{
			"id": 720,
			"code": "free shipping",
			"amount": "0.00",
			"date_created": "2017-03-21T15:25:02",
			"date_created_gmt": "2017-03-21T18:25:02",
			"date_modified": "2017-03-21T15:25:02",
			"date_modified_gmt": "2017-03-21T18:25:02",
			"discount_type": "fixed_cart",
			"description": "",
			"date_expires": null,
			"date_expires_gmt": null,
			"usage_count": 0,
			"individual_use": true,
			"product_ids": [],
			"excluded_product_ids": [],
			"usage_limit": null,
			"usage_limit_per_user": null,
			"limit_usage_to_x_items": null,
			"free_shipping": true,
			"product_categories": [],
			"excluded_product_categories": [],
			"exclude_sale_items": false,
			"minimum_amount": "0.00",
			"maximum_amount": "0.00",
			"email_restrictions": [],
			"used_by": [],
			"meta_data": [],
			"_links": {
				"self": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons/720"
					}
				],
				"collection": [
					{
						"href": "https://example.com/wp-json/wc/v3/coupons"
					}
				]
			}
		}
	]
}