woocommerce/woocommerce-rest-api-docs
1
0
Fork 0
mirror of https://gh.wpcy.net/https://github.com/woocommerce/woocommerce-rest-api-docs.git synced 2026-04-24 04:42:50 +08:00
Code Issues Projects Packages Activity Actions
woocommerce-rest-api-docs/source/includes/wp-api-v1/_coupons.md

25 KiB
Raw Permalink Blame History

Coupons

The coupons API allows you to create, view, update, and delete individual, or a batch, of coupon codes.

Coupon properties

Attribute Type Description
id integer Unique identifier for the object. read-only
code string Coupon code. mandatory
date_created date-time The date the coupon was created, in the site's timezone. read-only
date_modified date-time The date the coupon was last modified, in the site's timezone. read-only
description string Coupon description.
discount_type string Determines the type of discount that will be applied. Options: fixed_cart, percent, fixed_product and percent_product. Default: fixed_cart.
amount string The amount of discount.
expiry_date string UTC DateTime when the coupon expires.
usage_count integer Number of times the coupon has been used already. read-only
individual_use boolean Whether coupon can only be used individually.
product_ids array List of product ID's the coupon can be used on.
exclude_product_ids array List of product ID's the coupon cannot be used on.
usage_limit integer How many times the coupon can be used.
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 Define if can be applied for free shipping.
product_categories array List of category ID's the coupon applies to.
excluded_product_categories array List of category ID's the coupon does not apply to.
exclude_sale_items boolean Define if should not apply when have sale items.
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 who have used the coupon. read-only

Create a coupon

This API helps you to create a new coupon.

HTTP request

POST
/wp-json/wc/v1/coupons
curl -X POST https://example.com/wp-json/wc/v1/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"
}'

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

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


<?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));
?>

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())

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 example:

{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T21:55:54",
  "discount_type": "percent",
  "description": "",
  "amount": "10.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}

Retrieve a coupon

This API lets you retrieve and view a specific coupon by ID.

HTTP request

GET
/wp-json/wc/v1/coupons/<id>
curl https://example.com/wp-json/wc/v1/coupons/113 \
	-u consumer_key:consumer_secret

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

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

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

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

JSON response example:

{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T21:55:54",
  "discount_type": "percent",
  "description": "",
  "amount": "10.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}

List all coupons

This API helps you to list all the coupons that have been created.

HTTP request

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

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

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

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

woocommerce.get("coupons").parsed_response

JSON response example:

[
  {
    "id": 114,
    "code": "free-shipping",
    "date_created": "2016-04-28T21:58:25",
    "date_modified": "2016-04-28T21:58:25",
    "discount_type": "fixed_cart",
    "description": "",
    "amount": "0.00",
    "expiry_date": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "exclude_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": 0,
    "free_shipping": false,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": true,
    "minimum_amount": "50.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons/114"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons"
        }
      ]
    }
  },
  {
    "id": 113,
    "code": "10off",
    "date_created": "2016-04-28T21:55:54",
    "date_modified": "2016-04-28T21:55:54",
    "discount_type": "percent",
    "description": "",
    "amount": "10.00",
    "expiry_date": null,
    "usage_count": 0,
    "individual_use": true,
    "product_ids": [],
    "exclude_product_ids": [],
    "usage_limit": null,
    "usage_limit_per_user": null,
    "limit_usage_to_x_items": 0,
    "free_shipping": false,
    "product_categories": [],
    "excluded_product_categories": [],
    "exclude_sale_items": true,
    "minimum_amount": "100.00",
    "maximum_amount": "0.00",
    "email_restrictions": [],
    "used_by": [],
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons/113"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wc/v1/coupons"
        }
      ]
    }
  }
]

Available parameters

Parameter Type Description
context string Scope under which the request is made; determines fields present in response. Options: view and edit.
page integer Current page of the collection.
per_page integer Maximum number of items to be returned in result set.
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.
dates_are_gmt boolean Interpret after and before as UTC dates when true.
exclude string Ensure result set excludes specific ids.
include string 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. Default is asc. Options: asc and desc.
orderby string Sort collection by object attribute. Default is date, Options: date, id, include, title and slug.
code string Limit result set to resources with a specific code.

Update a coupon

This API lets you make changes to a coupon.

HTTP request

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

const data = {
  amount: 5
};

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

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

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

data = {
    "amount": 5
}

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

data = {
  amount: 5
}

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

JSON response example:

{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T22:00:49",
  "discount_type": "percent",
  "description": "",
  "amount": "5.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}

Delete a coupon

This API helps you delete a coupon.

HTTP request

DELETE
/wp-json/wc/v1/coupons/<id>
curl -X DELETE https://example.com/wp-json/wc/v1/coupons/113?force=true \
	-u consumer_key:consumer_secret

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

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

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

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

JSON response example:

{
  "id": 113,
  "code": "10off",
  "date_created": "2016-04-28T21:55:54",
  "date_modified": "2016-04-28T22:00:49",
  "discount_type": "percent",
  "description": "",
  "amount": "5.00",
  "expiry_date": null,
  "usage_count": 0,
  "individual_use": true,
  "product_ids": [],
  "exclude_product_ids": [],
  "usage_limit": null,
  "usage_limit_per_user": null,
  "limit_usage_to_x_items": 0,
  "free_shipping": false,
  "product_categories": [],
  "excluded_product_categories": [],
  "exclude_sale_items": true,
  "minimum_amount": "100.00",
  "maximum_amount": "0.00",
  "email_restrictions": [],
  "used_by": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons/113"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v1/coupons"
      }
    ]
  }
}

Available parameters

Parameter Type Description
force string Use true whether to permanently delete the coupon, Default is false.

Batch update coupons

This API helps you to batch create, update and delete multiple coupons.

HTTP request

POST
/wp-json/wc/v1/coupons/batch
curl -X POST https://example.com//wp-json/wc/v1/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": 113,
      "minimum_amount": "50.00"
    }
  ],
  "delete": [
    137
  ]
}'

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: 113,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    137
  ]
};

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

<?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' => 113,
            'minimum_amount' => '50.00'
        ]
    ],
    'delete' => [
        137
    ]
];

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

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": 113,
            "minimum_amount": "50.00"
        }
    ],
    "delete": [
        137
    ]
}

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

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: 113,
      minimum_amount: "50.00"
    }
  ],
  delete: [
    137
  ]
}

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

JSON response example:

{
  "create": [
    {
      "id": 138,
      "code": "20off",
      "date_created": "2016-05-17T20:52:21",
      "date_modified": "2016-05-17T20:52:21",
      "discount_type": "percent",
      "description": "",
      "amount": "20.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/138"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    },
    {
      "id": 139,
      "code": "30off",
      "date_created": "2016-05-17T20:52:22",
      "date_modified": "2016-05-17T20:52:22",
      "discount_type": "percent",
      "description": "",
      "amount": "30.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "100.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/139"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ],
  "update": [
    {
      "id": 113,
      "code": "10off",
      "date_created": "2016-04-28T21:55:54",
      "date_modified": "2016-05-17T20:52:23",
      "discount_type": "percent",
      "description": "",
      "amount": "5.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": true,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": true,
      "minimum_amount": "50.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/113"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ],
  "delete": [
    {
      "id": 137,
      "code": "50off",
      "date_created": "2016-05-17T20:49:12",
      "date_modified": "2016-05-17T20:50:30",
      "discount_type": "fixed_cart",
      "description": "",
      "amount": "50.00",
      "expiry_date": null,
      "usage_count": 0,
      "individual_use": false,
      "product_ids": [],
      "exclude_product_ids": [],
      "usage_limit": null,
      "usage_limit_per_user": null,
      "limit_usage_to_x_items": 0,
      "free_shipping": false,
      "product_categories": [],
      "excluded_product_categories": [],
      "exclude_sale_items": false,
      "minimum_amount": "0.00",
      "maximum_amount": "0.00",
      "email_restrictions": [],
      "used_by": [],
      "_links": {
        "self": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons/137"
          }
        ],
        "collection": [
          {
            "href": "https://example.com/wp-json/wc/v1/coupons"
          }
        ]
      }
    }
  ]
}